---
title: HTTP API
description: >-
  REST a https://api.linkdash.dev/v1 címen, a dashboardon létrehozott bearer
  kulccsal. Ugyanazok a műveletek, mint a CLI-ban és az MCP-ben.
sidebar:
  label: HTTP API
  order: 4
---
Alap URL: `https://api.linkdash.dev/v1`

Hitelesítés: `Authorization: Bearer ldash_...` (kulcsot a [Dashboard → API-kulcsok](https://linkdash.dev/dashboard/keys) oldalon hozhatsz létre). Ne találj ki kulcsokat.

CLI-referencia: [CLI](/hu/cli). MCP: [MCP](/hu/mcp). Árazás / kvóták: [Árazás](/hu/pricing). Felderítés (hitelesítés nélkül): `GET https://api.linkdash.dev/v1`. Sima markdown: [api.md](https://linkdash.dev/api.md).

A nyilvános azonosítók slugok (`deck`, `k3m9xq`), nem a Convex `_id`. A JSON-mezők nevei megegyeznek a CLI stdout kimenetében szereplőkkel (`id`, `url`, `kind`, …).

## Konvenciók

- JSON, `Content-Type: application/json`, hacsak másként nincs jelölve.
- A létrehozás pontosan egyet vár a következők közül: `url`, `text`, vagy `POST /uploads` után `storageId`, **vagy** egy `variants` tömböt (lásd [Változatok](#variants)), **vagy** `"kind": "folder"` értéket egy `name` mezővel (lásd [Mappák](#folders)). A feltöltési URL generálása `{ "uploadUrl", "storageId" }` értéket ad vissza. A host PUT kéréssel küldi fel a bájtokat az `uploadUrl` címre. Kis fájlokhoz továbbra is használhatod a multipart `file` mezőt a `POST /links` végponton.
- Időtartamok: `7d`, `24h`, `30m`, `1w` vagy ISO-dátum. Mezők: `expires` / `expiresAt`, `starts` / `startsAt`.
- Megnyitási korlát: opcionális, pozitív egész `maxOpenings`. A link ennyi sikeres megnyitás után szünetel. Ha újra ki akarod szolgálni, növeld a `maxOpenings` értékét, vagy használd a `clearMaxOpenings` mezőt. Korlátlan megnyitáshoz hagyd el a `maxOpenings` mezőt.
- Ha egy slug a tulajdonos két domainjén is létezik, add meg a `?domain=` paramétert / a JSON `domain` mezőt.
- Hibák: `{ "error": "..." }`, opcionálisan `code` mezővel. Foglalt `lida.sh` slug esetén a válasz `409`, `code: "slug_taken"` értékkel.
- Hozzáférés: az új linkek és mappák `restricted` hozzáférésűek, hacsak a body nem állítja be az `access` mezőt (lásd [Hozzáférés és megosztás](#access-and-sharing)). A válaszokban az `url` a megosztási URL (`https://linkdash.dev/s/<token>`), kivéve, ha a link nyilvános – ilyenkor a rövid URL.
- Az írások beleszámítanak a havi eseménykvótába (a share, az unshare és a reset is). A list / get / stats / export / shares list / shared / webhook list/get nem számít bele. A visit / download / play események rögzítése továbbra is beleszámít.

## Végpontok

| 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` (id nélkül) | `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` (`id` nélkül) |
| `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` |
| (host PUT a generálás után) | `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_*` |

Az `auth create`, az `auth login` és az `auth logout` böngészős device flow-k. Ezek nem Unkey-útvonalak.

## `GET /me`

A bejelentkezett fiók. `{ "userId": "...", "email": "...", "name": "..." }`. Az e-mail és a név kimarad, ha nem ismert.

## URL-link létrehozása

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

A JSON body pontosan egyet vár a következők közül: `url`, `text` vagy `storageId`, emellett opcionálisan: `access` (`restricted` az alapértelmezés \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (csak URL-linkeknél), valamint `folder` (+ `folderDomain`), ha mappán belül akarod létrehozni. A rövidített forma egyetlen, `main` nevű változatot hoz létre; a legfelső szintű `password`, `starts`, `expires` és `maxOpenings` a link kapuja. Válasz: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

A `GET /links` egy oldalt ad vissza, `{ "items": [...], "cursor" }` formában: a `?limit=` értéke 1-100 (alapértelmezés: 50); add át az előző oldalból kapott `?cursor=` értéket, amíg az `null` nem lesz. A `q` egész szavakra illeszkedik (az utolsó szóra prefixként), relevancia szerint rangsorolva. Az elemek alakja `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (a mappasorok `items` mezőt is kapnak); a `kind` szűrő a `folder` és a `group` értékkel bővül, a `status` szűrő a `mixed` értékkel, a `folder=<slug>|root` (+ `folderDomain`) pedig egy mappát vagy a legfelső szintet listázza. A `GET /links/:id` a teljes linket adja vissza `access` és `variants` mezőkkel; a tartalom (`destinationUrl` / `textContent` / `fileName`) az egyes változatokon található.

## Fájl feltöltése

Generálj egy feltöltési URL-t (`{uploadUrl,storageId}`), töltsd fel a bájtokat PUT-tal a hostról, majd ugyanabban a folyamatban hozd létre a linket:

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

Kis fájlokhoz továbbra is használhatod a multipartot a `POST /links` végponton:

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

Opcionális multipart mezők: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Frissítés, statisztika, CSV

A `PATCH /links/:id` JSON-t vagy multipartot fogad. A fájl bájtjait lecserélheted `storageId`-vel (`POST /uploads` + host PUT után), vagy a `file` multipart mezővel (csak egyváltozatos linkeknél). A `--status` / `{ "status": "expired" }` elutasításra kerül – használd az `expires` mezőt. A `{ "status": "scheduled" }` is elutasításra kerül – használd a `starts` mezőt. Az opcionális `maxOpenings` ennyi megnyitás után szünetelteti a linket; a `clearMaxOpenings` eltávolítja a korlátot. A `sticky` (boolean) és a `restartSplit` (boolean) a változatok kiosztását vezérli; a `forwardParams` (boolean) továbbítja a látogató query stringjét, lásd [Query paraméterek továbbítása](#forward-query-parameters). Az `access` azt szabályozza, ki nyithatja meg; a `resetShareLink: true` új megosztási URL-t ad ki. Válasz: `{ "id", "url", "access", "status", "variantStatuses" }`.

A `GET /links/:id/stats?last=24h` a következőket adja vissza: `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (változatonkénti összesítések), `visitors` és `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: botok és linkelőnézetek, amelyek lekérték a linket – ezek sosem számítanak látogatásnak; lásd [Crawler-napló](https://linkdash.dev/pricing.md)).

A `GET /links/export` CSV-t ad vissza a következő oszlopokkal: `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, változatonként egy sorral (a `folder` a tartalmazó mappa slugja; az `access` értéke `restricted`, `link` vagy `public`). A `POST /links/import` nyers CSV-t vagy multipart `file` mezőt fogad; a sorok slug + domain szerint csoportosulnak (az első sor létrehozza a linket a változatával, a további sorok változatokat adnak hozzá; meglévő linkeknél előbb a mezők frissülnek, majd név szerint frissülnek vagy hozzáadódnak a változatok). A `folder` `kind` értékű sorok (`name` mezővel) mappákat hoznak létre, a `folder` oszlop pedig csak azután helyezi el a linkeket, hogy minden sor létrejött. Üres `access` esetén az új linkek korlátozottak lesznek, a meglévők pedig változatlanok maradnak.

A `DELETE /links/:id` mappa esetén a `?contents=keep` (alapértelmezés: az elemek egy szinttel feljebb kerülnek) vagy a `?contents=delete` (a benne lévő elemek és mappák is törlődnek) paramétert fogadja.

## Változatok

Minden link egy vagy több **változat** tárolója. Egy változat tartalomból (`url` | `file` | `text`), saját kapuból (`password`, `paused`, `starts`, `expires`, `maxOpenings`), egy `weight` értékből és opcionális látogatói feltételekből (`when`) áll. A linkhez tartozik a slug, a domain, a név, a címkék, az előnézet, a saját kapuja (amely felülírja a változatok kapuit), a `sticky` (alapértelmezés: `true`) és a `splitVersion` (ezt a `restartSplit` növeli). `variants` nélkül a linknek egyetlen, `main` nevű változata van. Nevek: kisbetűk, számjegyek, belső kötőjelek, 1–40 karakter, linkenként egyediek. Linkenként legfeljebb 20 változat lehet.

A látogató egy változatot kap: a készletet azok a változatok alkotják, amelyek `when` feltétele illeszkedik (ha egyik sem illeszkedik, akkor a feltétel nélküliek), ebből súlyozott választás történik (a látogató + link + `splitVersion` sticky hash-e alapján, egyébként véletlenszerűen). A crawlerek az első élő, feltétel nélküli változatot kapják. Több változat esetén a link `kind` értéke `group`. A link `status` értéke a link kapuja, ha az be van állítva; ha nincs, akkor az a státusz, amely minden változatnál azonos; egyébként `mixed`. A `variantStatuses` a `{ active, paused, expired, scheduled }` darabszámokat tartalmazza.

Több változat létrehozása egyszerre:

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

Minden változat mezői: `name` (kötelező), egy a következők közül: `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), továbbá `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. A multipart létrehozás továbbra is csak a rövidített formát támogatja.

| Útvonal | Body | Válasz |
| --- | --- | --- |
| `GET /links/:id/variants` | — | a változatok tömbje |
| `POST /links/:id/variants` | JSON vagy multipart `file`: `name` (kötelező), tartalom, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | a változat |
| `PATCH /links/:id/variants/:name` | `name` (átnevezés), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | a változat |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (az utolsó változat nem törölhető) |

A `when` kulcsai (stringtömbök; minden beállított kulcsnak illeszkednie kell): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (prefix), `referrerHosts` (host-utótag).

### Query paraméter szabályok

A `when.params` legfeljebb 10 szabályból álló tömb, amely a látogató query stringjére vonatkozik (`lida.sh/promo?src=newsletter`); minden szabálynak teljesülnie kell. Minden szabály `{ "key", "op", "value" }` alakú, ahol az `op` a következők egyike: `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (a `value` `|`-vel vagy vesszővel elválasztott lista) | `exists` | `missing`. A `value` kötelező, kivéve `exists` / `missing` esetén. A kulcsok kis- és nagybetűérzékenyek, az értékeket pontos egyezésre vizsgálja.

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

A paraméterértékek illesztése megnyitáskor történik, és ezek sosem kerülnek tárolásra az analitikában.

### Query paraméterek továbbítása

A `forwardParams` (boolean a linken, alapértelmezés: `false`; beállítható a `POST /links` és a `PATCH /links/:id` végponton, a `GET /links/:id` visszaadja) a látogató teljes query stringjét hozzáfűzi az URL-változatokhoz. A látogató által küldött értékek felülírják a tároltakat, az `utm`-et is beleértve. A fájl- és szövegváltozatok figyelmen kívül hagyják. Ez útválasztás, nem hozzáférés-szabályozás: bárki hozzáadhat paramétereket. A paraméterértékek nem kerülnek tárolásra az analitikában.

## Mappák

A mappa egy olyan link, amely felsorolja a beletett elemeket. A modellről a [Mappák](/hu/folders) oldalon olvashatsz.

```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_..."
```

| Útvonal | Body | Válasz |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` plusz a szokásos linkmezők; `url`, `text`, `storageId` és `variants` nélkül | a létrehozott mappa |
| `POST /links/:id/move` | `{ "folder": "<slug>" }`, vagy a legfelső szinthez `{ "folder": null }`, opcionálisan `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (azonos hozzáférés, új megosztási URL, megosztott személyek nélkül) |

Az áthelyezés és a másolás egyaránt egy eseménynek számít. Ismeretlen mappaslug esetén a válasz `404` (`Folder "<slug>" not found`); ha a slug nem mappa, vagy egy mappát önmagába vagy egy alatta lévő mappába helyeznél át, a válasz `400`. A mappák legfeljebb 32 szint mélyen ágyazhatók egymásba.

## Hozzáférés és megosztás

Minden linknek és mappának van `access` értéke: `restricted` (alapértelmezés; a tulajdonos és azok, akikkel megosztották, bejelentkezve, a `https://linkdash.dev/s/<token>` címen), `link` (bárki, akinél megvan az URL) vagy `public` (bárki, a rövid URL-en). A `POST /links` vagy a `PATCH /links/:id` végponton állíthatod be. Nyilvános közzétételre szánt linkekhez add meg az `"access": "public"` értéket. A mappák és a megtekintők működéséről a [Megosztás és hozzáférés](/hu/sharing) oldalon olvashatsz.

```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_..."
```

| Útvonal | Body | Válasz |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 e-mail-cím) | `{ "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" }` (minden, amit megosztottál) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (az `:id` a `GET /shared` által visszaadott `_id` vagy megosztási token) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

Szerkesztők meghívásához a `POST /links/:id/shares` a `"role": "editor"` értéket fogadja. A szerkesztők módosíthatják az elemeket, és látják a statisztikákat és az aktivitást, de a jelszavakhoz, a slughoz, a domainhez, a hozzáféréshez és a megosztáshoz sosem nyúlhatnak, és nem törölhetnek, helyezhetnek át vagy másolhatnak (`403`). `:id`-ként az elem `_id` értékét vagy megosztási tokenjét használják, a jelszóval védett változat pedig `locked: true` marad, amíg nem hívják meg a `POST /links/:id/unlock` végpontot (30 percre; óránként tíz hibás jelszó után `429`). Ha valaki más közben már mentett, a mentés csak akkor ad `409`-et, ha a kérés `expectedVersion` értéket küld. Minden megosztási útvonal elfogadja a `?domain=` paramétert, ha a slug több domainen is szerepel. Az `accepted` értéke `false`, amíg az adott e-mail-címhez nincs ellenőrzött fiók; a `viaFolder` azt jelenti, hogy a hozzáférés egy feljebb lévő mappából öröklődik. Elemenként legfeljebb 200 személy lehet, és fiókonként naponta legfeljebb 100 meghívó e-mail mehet ki. A `GET /shares` és a `GET /shared` egyszerre egy oldalt ad vissza: a `?limit=` értéke 1-100 (alapértelmezés: 50); add át az előző oldalból kapott `?cursor=` értéket, amíg a `cursor` `null` nem lesz. A megosztás, a megosztás visszavonása és a reset egyenként egy eseménynek számít; a kilépés nem. Ha egy feljebb lévő megosztott mappán keresztül is van hozzáférésed, az kilépés után is megmarad.

## Hibák

| Státusz | Mikor |
| --- | --- |
| 400 | Validációs hiba, hiányzó body, vegyes létrehozási típusok |
| 401 | Hiányzó vagy érvénytelen bearer kulcs |
| 404 | Ismeretlen slug, domain vagy mappa |
| 409 | Foglalt slug (`code: "slug_taken"`) |
| 429 | Elérted a havi eseménykvótát |
| 503 | Ezen a telepítésen nincsenek konfigurálva API-kulcsok |

Ezekről a végpontokról a [webhookok](/hu/webhooks) és az [egyéni domainek](/hu/domains) oldalon olvashatsz.
