Pagination and idempotency

​

Pagination

​

Which lists are paged

​

How it works

• Pass limit to set the page size, from 1 to the largest page above. Anything else returns 400 invalid_request.
• Each page returns nextCursor. Pass it back unchanged as cursor to get the next page.
• nextCursor is null on the last page.
• Treat the cursor as opaque. Never build or edit one; a cursor the API did not issue returns 400 invalid_request.

​

Walk every page

cursor=""
while :; do
  page=$(curl -s "https://yungle.co/api/v1/transfers?limit=500${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $YUNGLE_API_KEY")
  echo "$page" | jq -r '.transfers[] | "\(.id)  \(.title // "-")  \(.status)"'
  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done

import { YungleClient } from 'yungle-client';

const yungle = new YungleClient({ apiKey: process.env.YUNGLE_API_KEY });

// allTransfers() fetches page after page as you iterate.
for await (const t of yungle.allTransfers()) {
  console.log(t.id, t.title ?? '-', t.status);
}

// Or one page at a time:
const { transfers, nextCursor } = await yungle.listTransfers({ limit: 100 });

from yungle import Yungle

yungle = Yungle()

# all_transfers() fetches page after page as you iterate.
for t in yungle.all_transfers():
    print(t["id"], t["title"] or "-", t["status"])

# Or one page at a time:
page = yungle.list_transfers(limit=100)
next_cursor = page["nextCursor"]

{
  "transfers": [
    { "id": "01JA8Z6Q2K3M4N5P6R7S8T9V0W", "title": "Q3 report", "status": "active", ... }
  ],
  "nextCursor": "v1.MDFKQThaNlEySzNNNE41UDZSN1M4VDlWMFc"
}

​

Idempotency

​

Send a key

curl -X POST https://yungle.co/api/v1/transfers \
  -H "Authorization: Bearer $YUNGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4e2a-9c3f-8d5e1b0a7c64" \
  -d '{"title":"Q3 report","files":[{"name":"report.pdf","size":2481152}]}'

​

What happens on a retry

​

Rules

• Only POST reads the header. Other methods ignore it.
• A key is remembered for 24 hours after its first use.
• Idempotency keys are scoped to the workspace. Two API keys in the same workspace share them.
• A key is bound to the request: its method, path and exact body. Reusing it for anything else gets idempotency_key_reused.
• The format is 1 to 255 printable ASCII characters, with no spaces. A UUID works. Anything else returns 400 invalid_request.

​

Requests that are safe to retry without a key

• Sending a transfer. Finalizing an already-sent transfer does not send it again or email anyone twice.
• Creating a transfer makes a new draft each time. A draft that is never sent is deleted after 24 hours, so a duplicate costs nothing, but a key avoids it.

​

Next steps