Retries and polling

​

You choose the IDs

• PUT /api/reports/{report_id} with the same ID never makes a second report.
• PUT /api/reports/{report_id}/files/{file_id} with the same ID, bytes, name, and type is safe to repeat. Different content with the same ID gives 409 file_conflict.

​

Revisions

1. Send revision: 0 to create a draft.
2. Send the revision from the last response with each next change.
3. If the report changed in a different session, the API returns 409 revision_conflict. The body has current, the stored report. Merge your change into current, then send it again with current.revision.

​

Safe actions

​

Page through reports

1. Send the first request with no cursor.
2. If next_cursor is not null, send it as cursor to get the next page.
3. Stop when next_cursor is null.

​

Poll for triage changes

1. Keep since: the newest updated_at that you saw. Use the Z form that the API returns, for example 2026-10-01T12:00:00Z.
2. Send GET /api/reports?updated_since=<since>. URL-encode the value. A raw + in a URL is a space.
3. Read all pages with next_cursor.
4. Set since to the newest updated_at on the first page.
5. For each report with status needs_info, read the thread and reply.

import os
import time
import requests

API = "https://kalligator.com/api"
HEADERS = {"Authorization": f"Bearer {os.environ['KALLIGATOR_API_KEY']}"}


def changed_reports(since):
    params = {"updated_since": since} if since else {}
    while True:
        page = requests.get(f"{API}/reports", headers=HEADERS, params=params, timeout=30)
        page.raise_for_status()
        body = page.json()
        yield from body["reports"]
        if not body["next_cursor"]:
            return
        params["cursor"] = body["next_cursor"]


since = None
while True:
    reports = list(changed_reports(since))
    if reports:
        since = reports[0]["updated_at"]
    for report in reports:
        if report["status"] == "needs_info":
            print("Needs your reply:", report["id"], report["title"])
    time.sleep(60)