Public API

import os
import httpx

client = httpx.Client(
    base_url="https://ttp-api.aldatalabs.com/v1/public",
    headers={"Authorization": f"Bearer {os.environ['TTP_KEY']}"},
    timeout=30,
)

boards = client.get("/boards").raise_for_status().json()
for board in boards["items"]:
    print(board["platform_board_id"], board["name"])

export TTP_KEY=ttp_8fktxx2z_...

curl -H "Authorization: Bearer $TTP_KEY" \
     https://ttp-api.aldatalabs.com/v1/public/boards

const BASE = "https://ttp-api.aldatalabs.com/v1/public";

const response = await fetch(`${BASE}/boards`, {
  headers: { Authorization: `Bearer ${process.env.TTP_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

const boards = await response.json();
for (const board of boards.items) {
  console.log(board.platform_board_id, board.name);
}

def every_page(path, **params):
    """Yields every row, following the cursor."""
    cursor = None
    while True:
        page = client.get(path, params={**params, "cursor": cursor, "limit": 100})
        page.raise_for_status()
        body = page.json()
        yield from body["items"]
        cursor = body["next_cursor"]
        if cursor is None:
            return


for card in every_page("/items", board_id="65a1b2c3d4e5f60718293a4b"):
    print(card["platform_item_id"], card["name"])

curl -H "Authorization: Bearer $TTP_KEY" \
     "$BASE/items?limit=100"
# -> "next_cursor": 417

curl -H "Authorization: Bearer $TTP_KEY" \
     "$BASE/items?limit=100&cursor=417"
# -> "next_cursor": null   (done)

async function* everyPage(path, params = {}) {
  let cursor = null;
  for (;;) {
    const query = new URLSearchParams({ ...params, limit: "100" });
    if (cursor !== null) query.set("cursor", String(cursor));

    const response = await fetch(`${BASE}${path}?${query}`, { headers });
    if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

    const body = await response.json();
    yield* body.items;
    if (body.next_cursor === null) return;
    cursor = body.next_cursor;
  }
}

entries = client.get(
    "/time-entries",
    params={
        "item_id": "6b0c1d2e3f4a5b6c7d8e9f01",
        "fields": "id,started_at,duration_seconds",
    },
).raise_for_status().json()

print(entries["items"])

curl -H "Authorization: Bearer $TTP_KEY" \
     "$BASE/time-entries?item_id=6b0c1d2e3f4a5b6c7d8e9f01&fields=id,started_at,duration_seconds"

const query = new URLSearchParams({
  item_id: "6b0c1d2e3f4a5b6c7d8e9f01",
  fields: "id,started_at,duration_seconds",
});

const entries = await (await fetch(`${BASE}/time-entries?${query}`, { headers })).json();
console.log(entries.items);

def call(path, **params):
    """Turns the documented codes into something a script can branch on."""
    response = client.get(path, params=params)

    if response.status_code == 429:
        raise RuntimeError(f"rate limited; retry after {response.headers['Retry-After']}s")
    if response.status_code == 403:
        raise PermissionError(response.json()["detail"].get("code", "forbidden"))
    if response.status_code == 404:
        return None          # absent, or not in this key's scope

    response.raise_for_status()
    return response.json()

async function call(path, params = {}) {
  const query = new URLSearchParams(params);
  const response = await fetch(`${BASE}${path}?${query}`, { headers });

  if (response.status === 429) {
    throw new Error(`rate limited; retry after ${response.headers.get("Retry-After")}s`);
  }
  if (response.status === 403) {
    const { detail } = await response.json();
    throw new Error(detail.code ?? "forbidden");
  }
  if (response.status === 404) return null; // absent, or not in this key's scope

  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return response.json();
}

def register_card(board, card, name, list_id=None, list_name=None):
    """Idempotent: call it before every write, it will not duplicate."""
    response = client.post(
        "/items",
        json={
            "platform_board_id": board,
            "platform_item_id": card,
            "name": name,
            "platform_list_id": list_id,  # both or neither
            "list_name": list_name,
        },
    )
    if response.status_code == 409:
        raise RuntimeError(f"{card} belongs to another board")
    response.raise_for_status()
    return response.json(), response.status_code == 201


card, created = register_card(board_id, "6b0c1d2e3f4a5b6c7d8e9f77", "Nightly rebuild")
print(card["name"], "created" if created else "already known")

curl -X POST \
     -H "Authorization: Bearer $TTP_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "platform_board_id": "65a1b2c3d4e5f60718293a4b",
           "platform_item_id": "6b0c1d2e3f4a5b6c7d8e9f77",
           "name": "GR: Formats: nightly rebuild",
           "platform_list_id": "65a1b2c3d4e5f6071829d001",
           "list_name": "Doing"
         }' \
     "$BASE/items"

async function registerCard(board, card, name, listId = null, listName = null) {
  const response = await fetch(`${BASE}/items`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      platform_board_id: board,
      platform_item_id: card,
      name,
      platform_list_id: listId, // both or neither
      list_name: listName,
    }),
  });

  if (response.status === 409) throw new Error(`${card} belongs to another board`);
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return { card: await response.json(), created: response.status === 201 };
}

card = client.put(
    f"/items/{card_id}/estimate",
    json={"estimate_seconds": 36000},   # None clears it
).raise_for_status().json()

print(card["estimate_seconds"])   # 36000

curl -X PUT \
     -H "Authorization: Bearer $TTP_KEY" \
     -H "Content-Type: application/json" \
     -d '{"estimate_seconds": 36000}' \
     "$BASE/items/6b0c1d2e3f4a5b6c7d8e9f01/estimate"

const response = await fetch(`${BASE}/items/${cardId}/estimate`, {
  method: "PUT",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ estimate_seconds: 36000 }), // null clears it
});
const card = await response.json();

card = client.put(
    f"/items/{card_id}/enrichment",
    json={
        "ai_result_formatted": "Rebuilt the nightly ETL.",
        "ai_result_recommended_hours": "8.50",   # decimal as a string
        "ai_result_verification": {"verified": True, "confidence": 0.92},
    },
).raise_for_status().json()

print(card["ai_result_formatted_at"])   # stamped by the server

curl -X PUT \
     -H "Authorization: Bearer $TTP_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "ai_result_formatted": "Rebuilt the nightly ETL.",
           "ai_result_recommended_hours": "8.50",
           "ai_result_verification": {"verified": true, "confidence": 0.92}
         }' \
     "$BASE/items/6b0c1d2e3f4a5b6c7d8e9f01/enrichment"

const response = await fetch(`${BASE}/items/${cardId}/enrichment`, {
  method: "PUT",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    ai_result_formatted: "Rebuilt the nightly ETL.",
    ai_result_recommended_hours: "8.50", // decimal as a string
    ai_result_verification: { verified: true, confidence: 0.92 },
  }),
});
const card = await response.json();

def log_time(card, member, started_at, seconds, run_id, note=None):
    """Idempotent: safe to retry with the same run_id."""
    response = client.post(
        "/time-entries",
        json={
            "platform_item_id": card,
            "platform_user_id": member,
            "started_at": started_at,       # must carry a UTC offset
            "duration_seconds": seconds,
            "note": note,
            "external_source": "hours-bridge",
            "external_id": run_id,
        },
    )
    if response.status_code == 409:
        raise RuntimeError(f"{run_id} already names a different entry")
    response.raise_for_status()
    return response.json()


entry = log_time(card_id, member_id, "2026-08-12T08:00:00Z", 3600, "run-001", "nightly")
print(entry["id"])

curl -X POST \
     -H "Authorization: Bearer $TTP_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "platform_item_id": "6b0c1d2e3f4a5b6c7d8e9f01",
           "platform_user_id": "5219e4d1b1a5b8f5a2000123",
           "started_at": "2026-08-12T08:00:00Z",
           "duration_seconds": 3600,
           "note": "nightly",
           "external_source": "hours-bridge",
           "external_id": "run-001"
         }' \
     "$BASE/time-entries"

async function logTime(card, member, startedAt, seconds, runId, note = null) {
  const response = await fetch(`${BASE}/time-entries`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      platform_item_id: card,
      platform_user_id: member,
      started_at: startedAt, // must carry a UTC offset
      duration_seconds: seconds,
      note,
      external_source: "hours-bridge",
      external_id: runId,
    }),
  });

  if (response.status === 409) throw new Error(`${runId} already names a different entry`);
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return response.json();
}

report = client.get(
    "/reports/grouped",
    params=[("group_by", "member"), ("group_by", "day"), ("tz", 180)],
).raise_for_status().json()

for row in report["rows"]:
    labels = " / ".join(cell["label"] for cell in row["cells"])
    print(f"{labels:32} {row['seconds'] / 3600:5.1f} h")

curl -H "Authorization: Bearer $TTP_KEY" \
     "$BASE/reports/grouped?group_by=member&group_by=day&tz=180"

const query = new URLSearchParams({ tz: "180" });
query.append("group_by", "member");
query.append("group_by", "day");

const report = await (await fetch(`${BASE}/reports/grouped?${query}`, { headers })).json();
for (const row of report.rows) {
  const labels = row.cells.map((cell) => cell.label).join(" / ");
  console.log(labels, (row.seconds / 3600).toFixed(1), "h");
}