Create up to 500 links in one call

THE CALL, PART BY PART

method

POST

host

strait.link

version

/v1

resource

/links/batch

POST /v1/links/batch

Auth: secret key as Authorization: Bearer. Server-side only.

Request

For imports and migrations. Each item passes the same checks as POST /v1/links (slug rules, https destinations, the unsafe-destination check, plan limits) and gets its own result; a bad item never fails the batch. A slug already used in the workspace (or earlier in the same batch) is a per-item 409, so re-running an import is safe. The response is 200 whenever the request itself is valid: read results[i].ok. Items past a plan limit get 402.

Parameters

Idempotency-Key string header
Optional (ADR 0055). Retry with the same key and the same body to get the first answer back (header Idempotent-Replayed: true) instead of running again. 1 to 255 of [A-Za-z0-9_.:-], kept 24 hours per workspace and endpoint. 5xx, 429 and 402 answers are not kept.

Body (JSON)

links required object[]

Response

  • 200 One result per item, in order, plus totals
  • 400 links is missing, empty, or has more than 500 items
  • 401 Missing or invalid secret key
Request · curl
curl -X POST https://strait.link/v1/links/batch \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      {
        "slug": "summer",
        "longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026"
      },
      {
        "slug": "winter",
        "longUrl": "https://shop.example.com/sale/winter"
      }
    ]
  }'

The response, printed

Response 200
{
  "results": [
    {
      "index": 0,
      "ok": true,
      "status": 201,
      "link": {
        "id": "lnk_5f0c2a8e-3b1d-4f6a-9c7e-2d8b1a0e4f63",
        "tenantId": "0b8f6d2e-7a41-4c39-9e15-3f2a6c8d1b70",
        "slug": "summer",
        "shortUrl": "https://hilltop.strait.link/summer",
        "longUrl": "https://shop.example.com/sale/summer?utm_source=whatsapp&utm_campaign=summer-2026",
        "isActive": true,
        "title": "Summer sale",
        "campaign": "summer-2026",
        "tags": [
          "sale"
        ]
      }
    },
    {
      "index": 1,
      "ok": false,
      "status": 409,
      "error": "slug already exists in this workspace"
    }
  ],
  "summary": {
    "total": 2,
    "created": 1,
    "failed": 1
  }
}