Sample code & write workflow

Pagination helper (Python)


import requests
 
BASE_URL = "https://<your-environment-host>"
TOKEN = "YOUR_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
 
def fetch_all_use_cases():
    all_records = []
    page = 0
    total_pages = 1
    while page < total_pages:
        resp = requests.get(
            f"{BASE_URL}/api/public/use-cases",
            headers=HEADERS,
            params={"page": page, "limit": 100},  # never exceed ~100
        )
        resp.raise_for_status()
        body = resp.json()
        all_records.extend(body["data"])
        total_pages = body.get("meta", {}).get("totalPages", 1)
        page += 1
    return all_records

Recommended write workflow

For any bulk load or scheduled sync job, AlignAI’s own reference script (populate_pipeline_fields.py, run as python3 populate_pipeline_fields.py test-data/uc4045_sample.csv --apply) follows this pattern — it’s worth replicating even if you’re not using the script itself:

Dry-run first

Don’t write on the first pass — log what you’d write and diff it against expectations.

Confirm token ↔ host match

Confirm the token and host match before any write (see Authentication & API keys — a mismatch fails with 401 Token does not exist, not a more obvious error).

Pull all records and index by `source_id`

Use the pagination helper above.

Per source row, branch on match count

0 matches → POST (create).
1 match → PATCH (update).
>1 matches → conflict — don’t guess; log it for manual review.

Throttle writes

Roughly one request every 0.2 seconds is a safe default against the public API.

Retry `429`/`5xx` with backoff

Don’t retry 400/401 — those need a code or credential fix, not a retry.

Re-pull and verify

Verify after writing, since there’s no single-record GET to confirm a PATCH inline (see Writing data).

Log a per-row HTTP status

Log a status for every write so a partial-failure batch can be re-run for just the failed rows.