POST /api/v1/links/bulk
Send an items or links array with no more than 100 entries.
Developer guide
Create short links in batches with the tt.vg API
Use the production bulk endpoint, handle partial results safely, reuse idempotency keys for retries, and connect link events to Webhooks.
links:bulk:create
The API key must include the bulk-create scope.
Idempotency-Key
Reuse one UUID for retries of the same batch to avoid duplicate creation and quota charges.
Copy and adapt
curl, JavaScript, and Python examples
Replace the API key and destinations. Each item accepts the same creation fields as the single-link API.
curl -X POST https://tt.vg/api/v1/links/bulk \
-H "Authorization: Bearer ttvg_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"items": [
{ "destinationUrl": "https://example.com/a", "description": "Campaign A" },
{ "destinationUrl": "https://example.com/b", "key": "campaign-b" }
]
}'Response handling
Treat results item by item
A batch can contain both successful links and validation errors. Save the returned item index with your own input record.
Every item succeeded
Read items and summary; errors is empty.
Partial success
Persist successful items and inspect each indexed error before retrying only the failed input.
Request or access error
Fix validation, authentication, email verification, or scope settings before retrying.
Quota or rate limit
Stop the batch and wait. Respect Retry-After when the rate limiter supplies it.
Temporary server failure
Retry with exponential backoff and the same Idempotency-Key.
Quota and batch limits
Each request accepts at most 100 links. Every successful item consumes one daily links:create unit from the account plan; failed items do not count as successful creates.
Continue with Webhooks
Subscribe to link.created, link.updated, or link.clicked. Delivery is signed, asynchronous, and retried without blocking the API response.
FAQ
Bulk API questions
Is bulk creation all-or-nothing?
No. Earlier valid items may succeed while later items return indexed errors; mixed results use HTTP 207.
What happens when quota runs out mid-batch?
The current and remaining items receive a 429 error and processing stops.
How do I prevent duplicate retries?
Send a random Idempotency-Key and reuse the same value only for retries of the identical batch.