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

Preverjanje pristnosti: `Authorization: Bearer ldash_...` (ključe ustvarite na [Nadzorna plošča → Ključi API](https://linkdash.dev/dashboard/keys)). Ključev si ne izmišljujte.

Referenca CLI: [CLI](/sl/cli). MCP: [MCP](/sl/mcp). Cene / kvote: [Cene](/sl/pricing). Odkrivanje (brez preverjanja pristnosti): `GET https://api.linkdash.dev/v1`. Navaden markdown: [api.md](https://linkdash.dev/api.md).

Javni ID-ji so slugi (`deck`, `k3m9xq`), ne Convex `_id`. Imena polj JSON se ujemajo z izhodom CLI na stdout (`id`, `url`, `kind`, …).

## Dogovori

- JSON `Content-Type: application/json`, razen če ni navedeno drugače.
- Ustvarjanje sprejme natanko eno od `url`, `text` ali `storageId` po `POST /uploads`, **ali** polje `variants` (glejte [Različice](#variants)), **ali** `"kind": "folder"` z `name` (glejte [Mape](#folders)). Ustvarjanje URL-ja za nalaganje vrne `{ "uploadUrl", "storageId" }`. Gostitelj z ukazom PUT pošlje bajte na `uploadUrl`. Majhne datoteke lahko še vedno uporabijo multipart `file` na `POST /links`.
- Trajanja: `7d`, `24h`, `30m`, `1w` ali datum ISO. Polja: `expires` / `expiresAt`, `starts` / `startsAt`.
- Omejitev odpiranj: izbirno pozitivno celo število `maxOpenings`. Povezava se po toliko uspešnih odpiranjih zaustavi. Povečajte `maxOpenings` ali uporabite `clearMaxOpenings`, da jo znova strežete. Za neomejeno število odpiranj izpustite `maxOpenings`.
- Če slug obstaja na dveh lastnikovih domenah, podajte `?domain=` / JSON `domain`.
- Napake: `{ "error": "..." }` in izbirno `code`. Zasedeni slugi `lida.sh` vrnejo `409` s `code: "slug_taken"`.
- Dostop: nove povezave in mape so `restricted`, razen če telo nastavi `access` (glejte [Dostop in deljenje](#access-and-sharing)). `url` v odgovorih je URL za deljenje (`https://linkdash.dev/s/<token>`), razen če je povezava javna; takrat je to kratki URL.
- Pisanja se štejejo v mesečno kvoto dogodkov (vključno z deljenjem, preklicem deljenja in ponastavitvijo). List / get / stats / export / seznam deljenj / shared / webhook list/get se ne štejejo. Zajem obiskov / prenosov / predvajanj se še vedno šteje.

## Končne 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` (brez id) | `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` (brez `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 gostitelja po ustvarjanju URL-ja) | `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` in `auth logout` so tokovi naprave v brskalniku. Niso poti Unkey.

## `GET /me`

Prijavljeni račun. `{ "userId": "...", "email": "...", "name": "..." }`. E-pošta in ime sta izpuščena, kadar nista znana.

## Ustvarjanje povezave URL

```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"}'
```

Telo JSON sprejme natanko eno od `url`, `text` ali `storageId`, poleg tega pa izbirno še `access` (`restricted` privzeto \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (samo povezave URL) in `folder` (+ `folderDomain`) za ustvarjanje znotraj mape. Skrajšana oblika ustvari eno različico z imenom `main`; `password`, `starts`, `expires` in `maxOpenings` na najvišji ravni so zapora povezave. Odgovor: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` vrne eno stran, `{ "items": [...], "cursor" }`: `?limit=` je 1-100 (privzeto 50); podajajte `?cursor=` iz prejšnje strani, dokler ni `null`. `q` se ujema s celimi besedami (zadnja kot predpona), rezultati so razvrščeni po ustreznosti. Elementi so `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (vrstice map dodajo `items`); filter `kind` doda `folder` in `group`, filter `status` doda `mixed`, `folder=<slug>|root` (+ `folderDomain`) pa izpiše eno mapo ali najvišjo raven. `GET /links/:id` vrne celotno povezavo z `access` in `variants`; vsebina (`destinationUrl` / `textContent` / `fileName`) je shranjena na posamezni različici.

## Nalaganje datoteke

Ustvarite URL za nalaganje (`{uploadUrl,storageId}`), z gostitelja pošljite bajte z ukazom PUT, nato v istem toku ustvarite povezavo:

```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}'
```

Majhne datoteke lahko še vedno uporabijo 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"
```

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

## Posodobitev, statistika, CSV

`PATCH /links/:id` je JSON ali multipart. Bajte datoteke zamenjajte s `storageId` po `POST /uploads` + PUT gostitelja ali s poljem multipart `file` (samo povezave z eno različico). `--status` / `{ "status": "expired" }` je zavrnjen — uporabite `expires`. `{ "status": "scheduled" }` je zavrnjen — uporabite `starts`. Izbirni `maxOpenings` zaustavi povezavo po toliko odpiranjih; `clearMaxOpenings` odstrani omejitev. `sticky` (boolean) in `restartSplit` (boolean) nadzorujeta dodeljevanje različic; `forwardParams` (boolean) posreduje poizvedbeni niz obiskovalca, glejte [Posredovanje parametrov poizvedbe](#forward-query-parameters). `access` spremeni, kdo jo lahko odpre; `resetShareLink: true` izda nov URL za deljenje. Odgovor: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` vrne `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (skupne vrednosti po različicah), `visitors` in `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: boti in predogledi povezav, ki so pridobili povezavo in se nikoli ne štejejo kot obiski; glejte [Dnevnik pajkov](https://linkdash.dev/pricing.md)).

`GET /links/export` je CSV s stolpci `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, z eno vrstico na različico (`folder` je slug mape, ki vsebuje povezavo; `access` je `restricted`, `link` ali `public`). `POST /links/import` sprejme surov CSV ali multipart `file`; vrstice so združene po slugu + domeni (prva vrstica ustvari povezavo z njeno različico, nadaljnje vrstice dodajo različice; pri obstoječih povezavah se posodobijo polja, nato pa se različice posodobijo ali dodajo po imenu). Vrstice s `kind` `folder` (z `name`) ustvarijo mape, stolpec `folder` pa povezave razporedi, ko obstajajo vse vrstice. Prazen `access` naredi nove povezave omejene, obstoječe pa pusti nespremenjene.

`DELETE /links/:id` na mapi sprejme `?contents=keep` (privzeto: elementi se premaknejo za raven višje) ali `?contents=delete` (izbrišejo se tudi elementi in mape v njej).

## Različice

Vsaka povezava je vsebnik ene ali več **različic**: vsebine (`url` | `file` | `text`) z lastno zaporo (`password`, `paused`, `starts`, `expires`, `maxOpenings`), utežjo `weight` in izbirnimi pogoji za obiskovalce `when`. Povezavi pripadajo slug, domena, ime, oznake, predogled, lastna zapora (ki ima prednost pred zaporami različic), `sticky` (privzeto `true`) in `splitVersion` (poveča ga `restartSplit`). Brez `variants` ima povezava eno različico z imenom `main`. Imena: male črke, števke, notranji vezaji, 1–40 znakov, edinstvena znotraj povezave. Največ 20 različic na povezavo.

Obiskovalec dobi eno različico: različice, katerih `when` se ujema, tvorijo nabor (če se nobena ne ujema, ga tvorijo brezpogojne različice), nato sledi utežena izbira (lepljiva zgoščena vrednost obiskovalca + povezave + `splitVersion`, sicer naključno). Pajki dobijo prvo aktivno brezpogojno različico. `kind` povezave je `group`, kadar ima več različic. `status` povezave je zapora povezave, kadar je nastavljena, sicer status, ki ga imajo vse različice, sicer `mixed`. `variantStatuses` šteje `{ active, paused, expired, scheduled }`.

Ustvarite več različic hkrati:

```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"]}}]}'
```

Vsaka različica: `name` (obvezno), eno od `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Ustvarjanje z multipart ostaja samo v skrajšani obliki.

| Pot | Telo | Odgovor |
| --- | --- | --- |
| `GET /links/:id/variants` | — | polje različic |
| `POST /links/:id/variants` | JSON ali multipart `file`: `name` (obvezno), vsebina, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | različica |
| `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` | različica |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (zadnje različice ni mogoče izbrisati) |

Ključi `when` (polja nizov; ujemati se mora vsak nastavljen ključ): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (predpona), `referrerHosts` (pripona gostitelja).

### Pravila parametrov poizvedbe

`when.params` je polje do 10 pravil za poizvedbeni niz obiskovalca (`lida.sh/promo?src=newsletter`); veljati mora vsako pravilo. Vsako pravilo je `{ "key", "op", "value" }`, pri čemer je `op` eno od `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` je seznam, ločen z `|` ali vejico) | `exists` | `missing`. `value` je obvezen, razen pri `exists` / `missing`. Ključi razlikujejo med velikimi in malimi črkami, vrednosti se primerjajo natančno.

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

Vrednosti parametrov se preverjajo ob odpiranju in se nikoli ne shranijo v analitiko.

### Posredovanje parametrov poizvedbe

`forwardParams` (boolean na povezavi, privzeto `false`; nastavljiv na `POST /links` in `PATCH /links/:id`, vrne ga `GET /links/:id`) različicam URL doda celoten poizvedbeni niz obiskovalca. Vrednosti obiskovalca preglasijo shranjene, vključno z `utm`. Različice z datoteko in besedilom ga prezrejo. To je usmerjanje, ne nadzor dostopa: parametre lahko doda kdorkoli. Vrednosti parametrov se ne shranjujejo v analitiko.

## Mape

Mapa je povezava, ki navaja elemente, ki jih vstavite vanjo. Za opis modela glejte [Mape](/sl/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_..."
```

| Pot | Telo | Odgovor |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` in običajna polja povezave; brez `url`, `text`, `storageId` ali `variants` | ustvarjena mapa |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` ali `{ "folder": null }` za najvišjo raven, izbirno `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (enak dostop, nov URL za deljenje, brez oseb) |

Premik in kopiranje se štejeta vsak kot en dogodek. Neznan slug mape vrne `404` (`Folder "<slug>" not found`); slug, ki ni mapa, ali premik mape vase ali v mapo pod njo vrne `400`. Mape je mogoče gnezditi največ 32 ravni globoko.

## Dostop in deljenje

Vsaka povezava in mapa ima `access`: `restricted` (privzeto; lastnik in osebe, s katerimi je deljena, ko so prijavljeni, na `https://linkdash.dev/s/<token>`), `link` (kdorkoli s tem URL-jem) ali `public` (kdorkoli, na kratkem URL-ju). Nastavite ga na `POST /links` ali `PATCH /links/:id`. Za povezave, namenjene javni objavi, podajte `"access": "public"`. Kako delujejo mape in gledalci, si oglejte v [Deljenje in dostop](/sl/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_..."
```

| Pot | Telo | Odgovor |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 e-poštnih naslovov) | `{ "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" }` (vse, kar ste delili) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` je `_id` ali žeton za deljenje iz `GET /shared`) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` za urednike sprejme `"role": "editor"`. Uredniki spreminjajo elemente ter vidijo statistiko in dejavnost, nikoli pa ne vidijo gesel in ne morejo spreminjati sluga, domene, dostopa in deljenja ter ne morejo brisati, premikati ali kopirati (`403`); kot `:id` uporabljajo `_id` elementa ali žeton za deljenje, različica, zaščitena z geslom, pa ostane `locked: true`, dokler ne pokličejo `POST /links/:id/unlock` (30 minut, deset napačnih gesel na uro, nato `429`). Shranjevanje, potem ko je shranil že nekdo drug, vrne `409` le, če zahteva pošlje `expectedVersion`. Vse poti za deljenje sprejmejo `?domain=`, kadar se slug ponavlja. `accepted` je `false`, dokler ta e-poštni naslov nima preverjenega računa; `viaFolder` pomeni, da dostop izhaja iz mape višje. Do 200 oseb na element in 100 e-poštnih povabil na račun na dan. `GET /shares` in `GET /shared` vračata eno stran naenkrat: `?limit=` je 1-100 (privzeto 50); podajajte `?cursor=` iz prejšnje strani, dokler `cursor` ni `null`. Deljenje, preklic deljenja in ponastavitev se štejejo vsak kot en dogodek; zapustitev se ne šteje. Dostop prek deljene mape višje ostane tudi po zapustitvi.

## Napake

| Stanje | Kdaj |
| --- | --- |
| 400 | Preverjanje veljavnosti, manjkajoče telo, mešane vrste ustvarjanja |
| 401 | Manjkajoč ali neveljaven ključ bearer |
| 404 | Neznan slug, domena ali mapa |
| 409 | Slug je zaseden (`code: "slug_taken"`) |
| 429 | Dosežena mesečna kvota dogodkov |
| 503 | Ključi API v tej namestitvi niso konfigurirani |

Za te končne točke glejte [webhooke](/sl/webhooks) in [domene po meri](/sl/domains).
