Bulk Link Creation with CSV: Import Hundreds of Links Safely

Manual link creation has a ceiling: around 30 links an hour with full attention. Teams that need hundreds of links — product feeds, print campaigns, migrations — hit that ceiling fast. The answer is the API and a disciplined batch script. This guide covers the pattern that works: rate limits, idempotency, collision handling, and verification.

The batch pattern

Every bulk job is the same loop:

read rows → build payloads → POST with rate-limit delay → collect results → report failures

With the yas.sh API, the safe rate is 60 creations per minute per user. A 1-second delay between calls keeps you under the limit even with retries:

#!/usr/bin/env bash
# links.csv: originalUrl,customAlias,title
while IFS=, read -r url alias title; do
  curl -s -X POST https://yas.sh/api/v1/links \
    -H "Authorization: Bearer yas_live_..." -H "Content-Type: application/json" \
    -d "{\"originalUrl\":\"$url\",\"customAlias\":\"$alias\",\"title\":\"$title\"}"
  sleep 1
done < links.csv

In Node.js, the same loop with fetch and a small delay library is a 30-line script; TypeScript example in the API reference.

Idempotency: retries without duplicates

Network failures happen mid-batch. Without protection, a retry creates a duplicate link. The API supports an Idempotency-Key header per row — typically the row number or a content hash:

curl -X POST https://yas.sh/api/v1/links \
  -H "Authorization: Bearer yas_live_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: row-0042" \
  -d '{"originalUrl":"https://example.com/42"}'

On retry with the same key, the API returns the existing link (200) instead of creating a second one. Your script treats both responses as success — the batch is naturally resumable.

Alias collisions: expect them, handle them

In a fresh namespace collisions are rare; in a migration or a shared workspace they're guaranteed. The API returns 409 Conflict with suggestions (launch-1, launch-2026). The batch script should:

1. Record the collision with the row reference.
2. Decide by policy: skip (destination already covered?) or retry with a deterministic suffix (e.g. -2, -3).
3. Write the final mapping (row → short link) to an output CSV — that file is your inventory.

Verification: prove the batch before you ship it

A batch isn't done when the last 201 arrives. Verification closes the loop:

# 1. Count check — exported links should match input rows
curl -H "Authorization: Bearer yas_live_..." "https://yas.sh/api/v1/links?limit=100" | jq '.data | length'

# 2. Spot-check redirects — a sample of codes must 302 correctly
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" https://yas.sh/launch

# 3. Full export for the record
curl -H "Authorization: Bearer yas_live_..." "https://yas.sh/api/v1/links/export.csv" -o inventory.csv

Spot-checking 5% of codes plus the export count catches the failure modes that matter: rows that silently failed, aliases that collided, and destinations that were wrong in the source data.

The migration angle

Bulk creation is the core of every migration. The Bitly migration guide and Short.io migration guide apply this same pattern with the export formats of those platforms, plus 301 forwarding so old links keep working during the transition window.

Operational checklist

• CSV is UTF-8, headers verified, formula-injection escaped (the export already is)
• Delay ≥1s between POSTs (60/min budget with headroom)
• Idempotency-Key per row
• Collision policy decided before the run
• Output mapping CSV written and committed
• 5% spot-check + export count verification

Conclusion

Bulk link creation is a solved problem when you script it: rate-limit-aware loops, idempotent retries, explicit collision policy, and post-run verification. The API reference has the full contract — the same endpoints power the dashboard, so what you script and what you click behave identically.