Bulk operations

Four endpoints take a batch instead of a single item. They share one response envelope, and one habit: read failed_count, not the HTTP status.

Operation	Path	Response `object`	Success array
Create redirects	`POST /v1/redirects/bulk`	`bulk_create_result`	`created`
Delete redirects	`POST /v1/redirects/bulk/delete`	`bulk_delete_result`	`deleted`
Add to a group	`POST /v1/groups/{id}/assign`	`bulk_assign_result`	`assigned`
Remove from a group	`POST /v1/groups/{id}/unassign`	`bulk_unassign_result`	`unassigned`

A batch costs 1 against your quota, however many items it contains. That is the main reason to use these endpoints. Every batch is 1–100 elements.

The response

The status is always 200, including when every element failed.

{
  "object": "bulk_create_result",
  "failed_count": 1,
  "created_count": 2,
  "created": [
    { "index": 0, "data": { "id": "rdr_9f2c…", "object": "redirect", "url": "https://teasy.link/promo" } },
    { "index": 2, "data": { "id": "rdr_1a2b…", "object": "redirect", "url": "https://teasy.link/sale" } }
  ],
  "failed": [
    {
      "index": 1,
      "error": {
        "code": "slug_already_taken",
        "message": "This address is already taken.",
        "value": "links.example.com/promo"
      }
    }
  ]
}

Check failed_count, not the HTTP status. A client that only checks response.ok will read a 200 full of failures as a success.

index is the position in the array you sent — for creation it is the only way to match a result back to your data. Creation and group operations return the resource in the flat list form, not the card. Deletion returns { id, object, deleted: true }.

const items = [
  { name: "Promo", target_url: "https://example.com/a", slug: "promo" },
  { name: "Sale", target_url: "https://example.com/b", slug: "sale" },
];

const res = await fetch("https://api.teasy.link/v1/redirects/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TEASY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ items }),
});

const result = await res.json();

for (const { index, data } of result.created) {
  console.log(`${items[index].name} -> ${data.url}`);
}

// A 200 can be full of failures, so this branch is not optional.
for (const { index, error } of result.failed) {
  console.error(`${items[index].name} failed: ${error.code}`, error.value);
}

items = [
    {"name": "Promo", "target_url": "https://example.com/a", "slug": "promo"},
    {"name": "Sale", "target_url": "https://example.com/b", "slug": "sale"},
]

res = requests.post(
    "https://api.teasy.link/v1/redirects/bulk",
    json={"items": items},
    headers={"Authorization": f"Bearer {os.environ['TEASY_KEY']}"},
)
result = res.json()

for entry in result["created"]:
    print(items[entry["index"]]["name"], "->", entry["data"]["url"])

# A 200 can be full of failures, so this branch is not optional.
for entry in result["failed"]:
    error = entry["error"]
    print(items[entry["index"]]["name"], "failed:", error["code"], error["value"])

Per-element errors

failed[].error has no HTTP status — only code, message and value. value is always present, null where there is nothing to point at. Offending data is not interpolated into message; read it from value.

`code`	When	`value`
`duplicate_id_in_batch`	The id appears more than once in the batch	`"rdr_9f2c…"`
`duplicate_slug_in_batch`	Two elements claim the same address	`"links.example.com/promo"`
`redirect_not_found` / `landing_not_found`	Passed ID is not able to interact	`"rdr_9f2c…"`
`group_not_found`	The element’s `group_id` is unknown	`"grp_4d8e…"`
`slug_already_taken`	The address is taken outside the batch	`"links.example.com/promo"`
`plan_limit_reached`	Your plan ran out of slots	`null`
`analytics_temporarily_unavailable`	Analytics could not be provisioned for this link	`null`
`domain_not_found`, `domain_not_active`, `slug_required_for_system_domain`	The element’s domain	`null`

What fails the whole request instead

Malformed input is rejected wholesale with 400: a bad prefix, a non-hex id, a batch that is too large or empty. Two more cases go the same way:

An unknown country code. Every unrecognised code is listed in details.
The group in the path. Unknown or not yours returns 404 group_not_found, since no element can be carried out without it.

Duplicates within a batch are treated per element, not as malformed input.

Fitting plan limits

When creating entities in bulk that are subject to limits, it’s important to understand how we handle them. We don’t reject the entire request if your current number of links plus N exceeds your plan limit. Instead, the system creates as many entities as allowed, in the order they were provided. The remaining ones will fail with plan_limit_reached.

Getting Started

Core Concepts

Working with the API

The response

Per-element errors

What fails the whole request instead

Fitting plan limits

​The response

​Per-element errors

​What fails the whole request instead

​Fitting plan limits

The response

Per-element errors

What fails the whole request instead

Fitting plan limits