---
title: HTTP API
description: >-
  REST na https://api.linkdash.dev/v1 s bearer ključem s nadzorne ploče. Iste
  operacije kao CLI i MCP.
sidebar:
  label: HTTP API
  order: 4
---
Osnovni URL: `https://api.linkdash.dev/v1`

Autentifikacija: `Authorization: Bearer ldash_...` (ključeve izradite na [Nadzorna ploča → API ključevi](https://linkdash.dev/dashboard/keys)). Ne izmišljajte ključeve.

CLI referenca: [CLI](/hr/cli). MCP: [MCP](/hr/mcp). Cijene / kvote: [Cijene](/hr/pricing). Otkrivanje (bez autentifikacije): `GET https://api.linkdash.dev/v1`. Običan markdown: [api.md](https://linkdash.dev/api.md).

Javni identifikatori su slugovi (`deck`, `k3m9xq`), a ne Convex `_id`. Nazivi JSON polja odgovaraju CLI stdoutu (`id`, `url`, `kind`, …).

## Konvencije

- JSON `Content-Type: application/json` osim ako nije drukčije navedeno.
- Izrada prima točno jedno od `url`, `text` ili `storageId` nakon `POST /uploads`, **ili** polje `variants` (pogledajte [Varijante](#variants)), **ili** `"kind": "folder"` s `name` (pogledajte [Mape](#folders)). Izdavanje URL-a za prijenos vraća `{ "uploadUrl", "storageId" }`. Host PUT-om šalje bajtove na `uploadUrl`. Male datoteke i dalje mogu koristiti multipart `file` na `POST /links`.
- Trajanja: `7d`, `24h`, `30m`, `1w` ili ISO datum. Polja: `expires` / `expiresAt`, `starts` / `startsAt`.
- Ograničenje otvaranja: neobavezni pozitivni cijeli broj `maxOpenings`. Poveznica se pauzira nakon toliko uspješnih otvaranja. Povećajte `maxOpenings` ili pošaljite `clearMaxOpenings` kako bi se ponovno posluživala. Izostavite `maxOpenings` za neograničen broj otvaranja.
- Ako slug postoji na dvije vlasnikove domene, proslijedite `?domain=` / JSON `domain`.
- Pogreške: `{ "error": "..." }` uz neobavezni `code`. Zauzeti `lida.sh` slugovi vraćaju `409` s `code: "slug_taken"`.
- Pristup: nove poveznice i mape su `restricted` osim ako tijelo zahtjeva ne postavi `access` (pogledajte [Pristup i dijeljenje](#access-and-sharing)). `url` u odgovorima je URL za dijeljenje (`https://linkdash.dev/s/<token>`), osim ako je poveznica javna, kada je to kratki URL.
- Operacije pisanja ubrajaju se u mjesečnu kvotu događaja (uključujući dijeljenje, prekid dijeljenja i resetiranje). Popis / dohvat / statistika / izvoz / popis dijeljenja / podijeljeno / popis i dohvat webhookova ne ubrajaju se. Unos posjeta / preuzimanja / reprodukcija i dalje se ubraja.

## Krajnje točke

| CLI | HTTP | MCP |
| --- | --- | --- |
| `auth whoami` | `GET /me` | `whoami` |
| `links list` | `GET /links` (`?q=&tag=&kind=&status=&folder=&limit=&cursor=`) | `links_list` |
| `links get <id>` | `GET /links/:id` (`?domain=`) | `links_get` |
| `links create --url/--file/--text/--folder` | `POST /links` | `links_create` |
| `links update <id>` | `PATCH /links/:id` | `links_update` |
| `links move <id>` | `POST /links/:id/move` | `links_move` |
| `links copy <id>` | `POST /links/:id/copy` | `links_copy` |
| `links delete <id>` | `DELETE /links/:id` (`?contents=keep\|delete`) | `links_delete` |
| `links share <id> --email <e>` | `POST /links/:id/shares` | `links_share` |
| `links unshare <id> --email <e>` | `DELETE /links/:id/shares/:email` | `links_unshare` |
| `links shares <id>` | `GET /links/:id/shares` | `links_shares` |
| `links shares` (bez id-a) | `PATCH /links/:id/shares/:email` | `{ "role": "viewer" \| "editor" }` | `{ "id", "email", "role" }` |
| `POST /links/:id/unlock` | `{ "variant"?, "password"?, "variantPassword"? }` | `{ "_id", "variant", "unlocked": true, "minutes": 30, ...target }` |
| `GET /links/:id/activity` | — | `{ "items": [{ "_id", "_creationTime", "action", "detail"?, "actor" }], "cursor" }` |
| `GET /shares` | `links_shares` (bez `id`) |
| `links shared` | `GET /shared` | `links_shared` |
| `links leave <_id \| share URL>` | `DELETE /shared/:id` | `links_leave` |
| `links role <id> --email <e> --role viewer\|editor` | `PATCH /links/:id/shares/:email` | `links_share_role` |
| `links unlock <_id \| share URL>` | `POST /links/:id/unlock` | `links_unlock` |
| `links activity <id>` | `GET /links/:id/activity` | `links_activity` |
| `links reset-link <id>` | `POST /links/:id/reset-link` | `links_update` (`resetShareLink: true`) |
| `links stats --last 24h` | `GET /links/:id/stats?last=24h` | `links_stats` |
| `links export` | `GET /links/export` | `links_export` |
| `links import` | `POST /links/import` | `links_import` |
| `links variants list <id>` | `GET /links/:id/variants` | `variants_list` |
| `links variants add <id>` | `POST /links/:id/variants` | `variants_add` |
| `links variants update <id> <name>` | `PATCH /links/:id/variants/:name` | `variants_update` |
| `links variants remove <id> <name>` | `DELETE /links/:id/variants/:name` | `variants_remove` |
| (PUT s hosta nakon izdavanja) | `POST /uploads` | `files_upload_url` |
| | `DELETE /uploads/:storageId` | `files_discard` |
| `webhooks list/create/get/rotate/delete` | `GET/POST /webhooks`, `GET/DELETE /webhooks/:id`, `POST /webhooks/:id/rotate` | `webhooks_*` |
| `domains list/add/connect/verify/remove` | `GET/POST /domains`, `GET /domains/:host/connect`, `POST /domains/:host/verify`, `DELETE /domains/:host` | `domains_*` |

`auth create`, `auth login` i `auth logout` tokovi su autorizacije uređaja putem preglednika. Nisu Unkey rute.

## `GET /me`

Prijavljeni račun. `{ "userId": "...", "email": "...", "name": "..." }`. E-pošta i ime izostavljaju se kada nisu poznati.

## Izrada URL poveznice

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","slug":"welcome","access":"public"}'
```

JSON tijelo prima točno jedno od `url`, `text` ili `storageId`, uz neobavezne `access` (`restricted` zadano \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (samo za URL poveznice) te `folder` (+ `folderDomain`) za izradu unutar mape. Skraćeni oblik izrađuje jednu varijantu naziva `main`; `password`, `starts`, `expires` i `maxOpenings` na najvišoj razini čine zaštitu poveznice. Odgovor: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` vraća jednu stranicu, `{ "items": [...], "cursor" }`: `?limit=` je 1-100 (zadano 50); prosljeđujte `?cursor=` s prethodne stranice dok ne bude `null`. `q` pronalazi podudaranja cijelih riječi (posljednje kao prefiksa), rangirana prema relevantnosti. Stavke su `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (retci mapa dodaju `items`); filtar `kind` dodaje `folder` i `group`, filtar `status` dodaje `mixed`, a `folder=<slug>|root` (+ `folderDomain`) ispisuje jednu mapu ili najvišu razinu. `GET /links/:id` vraća cijelu poveznicu s `access` i `variants`; sadržaj (`destinationUrl` / `textContent` / `fileName`) nalazi se na svakoj varijanti.

## Prijenos datoteke

Izdajte URL za prijenos (`{uploadUrl,storageId}`), PUT-om pošaljite bajtove s hosta, a zatim izradite poveznicu u istom toku:

```bash
curl https://api.linkdash.dev/v1/uploads \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"fileSize":12345}'

curl -X PUT -H "Content-Type: application/pdf" --data-binary @./deck.pdf "$uploadUrl"

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"storageId":"…","fileName":"deck.pdf","fileType":"application/pdf","fileSize":12345}'
```

Male datoteke i dalje mogu koristiti multipart na `POST /links`:

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"
```

Neobavezna multipart polja: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Ažuriranje, statistika, CSV

`PATCH /links/:id` prima JSON ili multipart. Bajtove datoteke zamijenite s `storageId` nakon `POST /uploads` + PUT-a s hosta ili multipart poljem `file` (samo za poveznice s jednom varijantom). `--status` / `{ "status": "expired" }` se odbija — koristite `expires`. `{ "status": "scheduled" }` se odbija — koristite `starts`. Neobavezni `maxOpenings` pauzira poveznicu nakon toliko otvaranja; `clearMaxOpenings` uklanja ograničenje. `sticky` (boolean) i `restartSplit` (boolean) upravljaju dodjelom varijanti; `forwardParams` (boolean) prosljeđuje posjetiteljev query string, pogledajte [Prosljeđivanje query parametara](#forward-query-parameters). `access` mijenja tko je može otvoriti; `resetShareLink: true` izdaje novi URL za dijeljenje. Odgovor: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` vraća `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (ukupni zbrojevi po varijanti), `visitors` i `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: botovi i pregledi poveznica koji su dohvatili poveznicu, a nikada se ne broje kao posjeti; pogledajte [Zapisnik crawlera](https://linkdash.dev/pricing.md)).

`GET /links/export` vraća CSV sa stupcima `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, jedan redak po varijanti (`folder` je slug mape u kojoj se poveznica nalazi; `access` je `restricted`, `link` ili `public`). `POST /links/import` prihvaća sirovi CSV ili multipart `file`; retci se grupiraju prema slugu + domeni (prvi redak izrađuje poveznicu s njezinom varijantom, daljnji retci dodaju varijante; postojećim poveznicama ažuriraju se polja, a zatim se varijante ažuriraju ili dodaju prema nazivu). Retci s `kind` `folder` (s `name`) izrađuju mape, a stupac `folder` smješta poveznice nakon što su obrađeni svi retci. Prazan `access` nove poveznice čini ograničenima, a postojeće ostavlja nepromijenjenima.

`DELETE /links/:id` na mapi prima `?contents=keep` (zadano: stavke se premještaju jednu razinu više) ili `?contents=delete` (brišu se i stavke i mape unutar nje).

## Varijante

Svaka poveznica spremnik je jedne ili više **varijanti**: sadržaja (`url` | `file` | `text`) s vlastitom zaštitom (`password`, `paused`, `starts`, `expires`, `maxOpenings`), težinom `weight` i neobaveznim uvjetima za posjetitelje `when`. Poveznici pripadaju slug, domena, naziv, oznake, pregled, vlastita zaštita (koja ima prednost pred zaštitama varijanti), `sticky` (zadano `true`) i `splitVersion` (povećava ga `restartSplit`). Bez `variants` poveznica ima jednu varijantu naziva `main`. Nazivi: mala slova, znamenke, unutarnje crtice, 1–40 znakova, jedinstveni unutar poveznice. Najviše 20 varijanti po poveznici.

Posjetitelj dobiva jednu varijantu: varijante čiji se `when` podudara čine skup za odabir (ako se nijedna ne podudara, skup čine bezuvjetne varijante), a zatim slijedi ponderirani odabir (sticky hash posjetitelja + poveznice + `splitVersion`, inače nasumično). Crawleri dobivaju prvu aktivnu bezuvjetnu varijantu. `kind` poveznice je `group` kada ima više varijanti. `status` poveznice je status zaštite poveznice kada je postavljena, inače status koji dijele sve varijante, inače `mixed`. `variantStatuses` broji `{ active, paused, expired, scheduled }`.

Izradite više varijanti odjednom:

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"promo","variants":[{"name":"a","url":"https://example.com/a"},{"name":"b","url":"https://example.com/b","weight":3,"when":{"countries":["DE","AT"]}}]}'
```

Svaka varijanta: `name` (obavezno), jedno od `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Izrada putem multiparta podržava samo skraćeni oblik.

| Ruta | Tijelo | Odgovor |
| --- | --- | --- |
| `GET /links/:id/variants` | — | polje varijanti |
| `POST /links/:id/variants` | JSON ili multipart `file`: `name` (obavezno), sadržaj, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | varijanta |
| `PATCH /links/:id/variants/:name` | `name` (preimenovanje), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | varijanta |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (posljednja varijanta ne može se izbrisati) |

Ključevi `when` (polja nizova znakova; svaki postavljeni ključ mora se podudarati): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefiks), `referrerHosts` (sufiks hosta).

### Pravila za query parametre

`when.params` je polje od najviše 10 pravila nad posjetiteljevim query stringom (`lida.sh/promo?src=newsletter`); sva pravila moraju biti zadovoljena. Svako pravilo ima oblik `{ "key", "op", "value" }`, pri čemu je `op` jedno od `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` je popis odvojen znakom `|` ili zarezom) | `exists` | `missing`. `value` je obavezan, osim za `exists` / `missing`. Ključevi razlikuju velika i mala slova, a vrijednosti se uspoređuju doslovno.

```json
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
```

Vrijednosti parametara provjeravaju se u trenutku otvaranja i nikada se ne pohranjuju u analitici.

### Prosljeđivanje query parametara

`forwardParams` (boolean na poveznici, zadano `false`; može se postaviti na `POST /links` i `PATCH /links/:id`, a vraća ga `GET /links/:id`) dodaje cijeli posjetiteljev query string URL varijantama. Posjetiteljeve vrijednosti nadjačavaju pohranjene, uključujući `utm`. Varijante s datotekom i tekstom zanemaruju ovu postavku. Ovo je usmjeravanje, a ne kontrola pristupa: svatko može dodati parametre. Vrijednosti parametara ne pohranjuju se u analitici.

## Mape

Mapa je poveznica koja ispisuje stavke koje u nju stavite. Za opis modela pogledajte [Mape](/hr/folders).

```bash
curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"folder","name":"Q4 launch","slug":"q4"}'

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/deck","folder":"q4"}'

curl https://api.linkdash.dev/v1/links/k3m9xq/move \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"folder":"q4"}'

curl "https://api.linkdash.dev/v1/links?folder=q4" -H "Authorization: Bearer ldash_..."
```

| Ruta | Tijelo | Odgovor |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` uz uobičajena polja poveznice; bez `url`, `text`, `storageId` ili `variants` | izrađena mapa |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` ili `{ "folder": null }` za najvišu razinu, neobavezno `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (isti pristup, novi URL za dijeljenje, bez osoba) |

Premještanje i kopiranje broje se svako kao jedan događaj. Nepoznati slug mape vraća `404` (`Folder "<slug>" not found`); slug koji nije mapa, kao i premještanje mape u samu sebe ili u mapu ispod nje, vraća `400`. Mape se mogu ugnježđivati najviše 32 razine duboko.

## Pristup i dijeljenje

Svaka poveznica i mapa ima `access`: `restricted` (zadano; vlasnik i osobe s kojima je podijeljena, uz prijavu, na `https://linkdash.dev/s/<token>`), `link` (svatko s tim URL-om) ili `public` (svatko, na kratkom URL-u). Postavite ga na `POST /links` ili `PATCH /links/:id`. Proslijedite `"access": "public"` za poveznice namijenjene javnom objavljivanju. Kako funkcioniraju mape i gledatelji, pogledajte u [Dijeljenje i pristup](/hr/sharing).

```bash
curl https://api.linkdash.dev/v1/links/q4/shares \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["anna@example.com","ben@example.com"]}'

curl https://api.linkdash.dev/v1/links/q4/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/links/q4/shares/ben%40example.com -H "Authorization: Bearer ldash_..."

curl -X POST https://api.linkdash.dev/v1/links/q4/reset-link -H "Authorization: Bearer ldash_..."

curl https://api.linkdash.dev/v1/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/shared/<_id> -H "Authorization: Bearer ldash_..."
```

| Ruta | Tijelo | Odgovor |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 adresa e-pošte) | `{ "id", "url", "access", "invited", "alreadyShared" }` |
| `DELETE /links/:id/shares/:email` | — | `{ "id", "email", "removed": true }` |
| `GET /links/:id/shares` | — | `[{ "email", "role": "viewer", "accepted", "invitedAt", "viaFolder"?: { "id", "name"?, "slug" } }]` |
| `GET /shares` | — | `{ "items": [{ "id", "name"?, "kind", "access", "url", "people": [{ "email", "accepted", "invitedAt" }] }], "cursor" }` (sve što ste podijelili) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` je `_id` ili token za dijeljenje iz `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` prima `"role": "editor"` za urednike. Urednici mijenjaju stavke te vide statistiku i aktivnost, ali nemaju pristup lozinkama, slugu, domeni, pristupu, dijeljenju, brisanju, premještanju ni kopiranju (`403`); kao `:id` koriste `_id` stavke ili token za dijeljenje, a varijanta zaštićena lozinkom ostaje `locked: true` do poziva `POST /links/:id/unlock` (30 minuta, deset pogrešnih lozinki na sat, zatim `429`). Spremanje nakon što je netko drugi već spremio vraća `409` samo kada zahtjev šalje `expectedVersion`. Sve rute za dijeljenje primaju `?domain=` kada se slug ponavlja. `accepted` je `false` dok ta adresa e-pošte nema potvrđeni račun; `viaFolder` znači da pristup proizlazi iz nadređene mape. Najviše 200 osoba po stavci i 100 e-poruka s pozivnicom po računu dnevno. `GET /shares` i `GET /shared` vraćaju po jednu stranicu: `?limit=` je 1-100 (zadano 50); prosljeđujte `?cursor=` s prethodne stranice dok `cursor` ne bude `null`. Dijeljenje, prekid dijeljenja i resetiranje broje se svako kao jedan događaj; napuštanje se ne broji. Pristup putem podijeljene nadređene mape ostaje i nakon napuštanja.

## Pogreške

| Status | Kada |
| --- | --- |
| 400 | Validacija, nedostaje tijelo zahtjeva, pomiješane vrste izrade |
| 401 | Bearer ključ nedostaje ili je nevažeći |
| 404 | Nepoznati slug, domena ili mapa |
| 409 | Slug je zauzet (`code: "slug_taken"`) |
| 429 | Dosegnuta je mjesečna kvota događaja |
| 503 | API ključevi nisu konfigurirani na ovoj implementaciji |

Za te krajnje točke pogledajte [webhookove](/hr/webhooks) i [prilagođene domene](/hr/domains).
