> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashlink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> The conventions that apply everywhere, worth knowing before you write much code.

Five things behave consistently across the whole API. Knowing them up front saves rediscovering each one through a confusing response.

## 1. Everything is wrapped

Success puts the payload under `data`. Failure puts the problem under `error`. They never both appear, so one check handles every endpoint:

```bash cURL theme={null}
# data and error never both appear, so one check covers every endpoint.
curl -s "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?per_page=1" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  | jq 'if .error then error(.error.message) else .data end'
```

```javascript Node.js theme={null}
const payload = await response.json();
if (payload.error) {
  throw new DashlinkError(payload.error.message, payload.error.code);
}
const result = payload.data;
```

```python Python theme={null}
payload = response.json()
if "error" in payload:
    raise DashlinkError(payload["error"]["message"], payload["error"].get("code"))
result = payload["data"]
```

```go Go theme={null}
var payload struct {
	Data  json.RawMessage `json:"data"`
	Error *struct {
		Message string `json:"message"`
		Code    string `json:"code"`
	} `json:"error"`
}
json.NewDecoder(resp.Body).Decode(&payload)

if payload.Error != nil {
	return nil, &DashlinkError{Message: payload.Error.Message, Code: payload.Error.Code}
}
result := payload.Data
```

```ruby Ruby theme={null}
payload = JSON.parse(response.body)
if payload.key?("error")
  raise DashlinkError.new(payload["error"]["message"], payload["error"]["code"])
end
result = payload["data"]
```

```php PHP theme={null}
<?php
$payload = json_decode($body, true);
if (isset($payload['error'])) {
    throw new DashlinkError($payload['error']['message'], $payload['error']['code'] ?? null);
}
$result = $payload['data'];
```

Branch on `error.code`, not `error.message` — messages get reworded and translated, codes do not. See [Errors](https://docs.dashlink.ai/api-reference/concepts/errors.md).

## 2. Deletion is bulk-only

There is no single-resource delete for links, QR codes or UTM templates. To delete one, send an array of one:

```bash cURL theme={null}
curl -X POST https://api.dashlink.ai/api/v1/shortlinks/bulk_delete_shortlinks \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -d 'shortlink_ids=["SHORT-0001"]'
```

```javascript Node.js theme={null}
await client.call("POST", "shortlinks/bulk_delete_shortlinks", {
  body: new URLSearchParams({
    shortlink_ids: JSON.stringify(["SHORT-0001"]),
  }),
});
```

```python Python theme={null}
client.call(
    "POST",
    "shortlinks/bulk_delete_shortlinks",
    data={"shortlink_ids": json.dumps(["SHORT-0001"])},
)
```

```go Go theme={null}
ids, _ := json.Marshal([]string{"SHORT-0001"})
form := url.Values{"shortlink_ids": {string(ids)}}

c.Call("POST", "shortlinks/bulk_delete_shortlinks",
	strings.NewReader(form.Encode()))
```

```ruby Ruby theme={null}
client.call("POST", "shortlinks/bulk_delete_shortlinks",
            shortlink_ids: JSON.generate(["SHORT-0001"]))
```

```php PHP theme={null}
<?php
$client->call('POST', 'shortlinks/bulk_delete_shortlinks', [
    'shortlink_ids' => json_encode(['SHORT-0001']),
]);
```

This means one code path and one result shape whether you are deleting one thing or a thousand. See [Bulk operations](https://docs.dashlink.ai/guides/links/bulk-operations.md).

> [!NOTE]
>
> Campaigns and domains are the exceptions — they have ordinary single deletes, because deleting them in bulk is not a thing anyone does.

## 3. Writes are form-encoded

`POST` bodies are `application/x-www-form-urlencoded`, or `multipart/form-data` when a file is involved. Not JSON.

Array and object parameters are sent as JSON-encoded strings inside the form:

```bash theme={null}
-d 'tags=["spring","email"]'
-d 'shortlinks=[{"destination_url":"https://example.com/a"}]'
```

The multipart endpoints are the ones that can carry an image: `create_shortlink`, `update_shortlink`, `create_dynamic_link`, `update_dynamic_link`, `create_qr_code`, `edit_qr_code`, and the two upload endpoints.

## 4. Lists paginate the same way

`page` and `per_page` in, four counts back:

```json theme={null}
{
  "data": {
    "links": [],
    "total_count": 247,
    "total_pages": 25,
    "current_page": 1,
    "per_page": 10
  }
}
```

`per_page` maxes at 100 and is clamped rather than rejected, so read back the value you were actually given. Loop until `current_page >= total_pages`. See [Pagination](https://docs.dashlink.ai/api-reference/concepts/pagination.md).

## 5. Not-yours looks like not-found

Asking for a resource that belongs to another organization returns `404`, not `403`. A `403` would confirm the id exists, which is all anyone needs to discover other customers' resources by trying ids until the status changes.

So a `404` means one of two things, and the API will not tell you which.

## Identifiers

Resources are referred to by their `name` — a generated id such as `SHORT-0001`, not the short URL:

| Resource | Looks like | Returned by |
| - | - | - |
| Shortlink | `SHORT-0001` | `create_shortlink`, `get_shortlinks` |
| QR code | `QR-0001` | `create_qr_code`, `get_qrcodes` |
| Campaign | `CAMP-0001` | `create_campaign`, `get_campaigns` |

The `back_half` is the path in the URL and is not an identifier — it can be changed, and two links on different domains can share one.

## Dates

`YYYY-MM-DD` everywhere. Analytics windows are inclusive of both `date_from` and `date_to`, and are bounded by your plan's [retention window](https://docs.dashlink.ai/guides/analytics/retention.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.