Skip to content
xQR Docs

Bulk Operations

The bulk endpoints let you create up to 100 links in a single request and update multiple links’ status at once.

Terminal window
curl -X POST https://xqr.co/api/v1/links/bulk \
  -H "Authorization: Bearer $XQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      {"url": "https://example.com/page-1", "labels": ["batch-1"]},
      {"url": "https://example.com/page-2", "labels": ["batch-1"]},
      {"url": "https://example.com/page-3", "custom_slug": "page3", "labels": ["batch-1"]}
    ]
  }'

Response

{
  "data": {
    "created": [
      {"id": "...", "short_code": "abc123", "destination": "https://example.com/page-1"},
      {"id": "...", "short_code": "def456", "destination": "https://example.com/page-2"},
      {"id": "...", "short_code": "page3", "destination": "https://example.com/page-3"}
    ],
    "errors": []
  }
}

If some links fail (e.g., slug conflict), they appear in the errors array while successful ones are still created.

Bulk Update Status

Enable or disable multiple links at once:

Terminal window
curl -X PATCH https://xqr.co/api/v1/links/bulk/status \
  -H "Authorization: Bearer $XQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["550e8400-...", "660e8400-...", "770e8400-..."],
    "enabled": false
  }'

Response

{
  "data": {
    "updated": 3
  }
}

Best Practices

  1. Batch by 100 — The API accepts up to 100 links per bulk request. For larger datasets, split into multiple requests.
  2. Handle partial failures — Check the errors array even when the request succeeds (200). Some individual links may fail while others succeed.
  3. Use labels — Tag bulk-created links with a common label for easy filtering and management.
  4. Rate limits apply — Each bulk request counts as one API call toward your monthly quota, but still consumes one burst token.

Was this page helpful?