---
title: HTTP-rajapinta
description: >-
  REST-rajapinta osoitteessa https://api.linkdash.dev/v1, todennus
  hallintapaneelista saatavalla bearer-avaimella. Samat toiminnot kuin CLI:ssä
  ja MCP:ssä.
sidebar:
  label: HTTP-rajapinta
  order: 4
---
Perus-URL: `https://api.linkdash.dev/v1`

Todennus: `Authorization: Bearer ldash_...` (luo avaimet kohdassa [Hallintapaneeli → API-avaimet](https://linkdash.dev/dashboard/keys)). Älä keksi avaimia itse.

CLI-viite: [CLI](/fi/cli). MCP: [MCP](/fi/mcp). Hinnoittelu / kiintiöt: [Hinnoittelu](/fi/pricing). Löytäminen (ei todennusta): `GET https://api.linkdash.dev/v1`. Pelkkä markdown: [api.md](https://linkdash.dev/api.md).

Julkiset tunnisteet ovat slugeja (`deck`, `k3m9xq`), eivät Convexin `_id`-arvoja. JSON-kenttien nimet vastaavat CLI:n stdout-tulostetta (`id`, `url`, `kind`, …).

## Käytännöt

- JSON, `Content-Type: application/json`, ellei toisin mainita.
- Luonti ottaa täsmälleen yhden kentistä `url`, `text` tai `storageId` (`POST /uploads` -kutsun jälkeen), **tai** `variants`-taulukon (katso [Variantit](#variants)), **tai** `"kind": "folder"` yhdessä `name`-kentän kanssa (katso [Kansiot](#folders)). Latausosoitteen luonti palauttaa `{ "uploadUrl", "storageId" }`. Isäntä lähettää tavut PUT-pyynnöllä osoitteeseen `uploadUrl`. Pienet tiedostot voi yhä lähettää multipart-kentässä `file` kutsulla `POST /links`.
- Kestot: `7d`, `24h`, `30m`, `1w` tai ISO-päivämäärä. Kentät: `expires` / `expiresAt`, `starts` / `startsAt`.
- Avauskertojen raja: valinnainen positiivinen kokonaisluku `maxOpenings`. Linkki keskeytyy, kun se on avattu onnistuneesti niin monta kertaa. Nosta `maxOpenings`-arvoa tai käytä `clearMaxOpenings`-kenttää, niin linkki toimii taas. Jätä `maxOpenings` pois, jos et halua rajaa.
- Jos sama slug on käytössä kahdella omistajan domainilla, anna `?domain=` / JSON-kenttä `domain`.
- Virheet: `{ "error": "..." }` sekä valinnainen `code`. Varatut `lida.sh`-slugit palauttavat `409`:n ja `code: "slug_taken"`.
- Käyttöoikeus: uudet linkit ja kansiot ovat `restricted`, ellei rungossa aseteta `access`-kenttää (katso [Käyttöoikeudet ja jakaminen](#access-and-sharing)). Vastauksissa `url` on jakolinkki (`https://linkdash.dev/s/<token>`), paitsi jos linkki on julkinen, jolloin se on lyhyt URL.
- Kirjoitukset lasketaan kuukausittaiseen tapahtumakiintiöön (myös jakaminen, jaon poisto ja nollaus). Listaus / haku / tilastot / vienti / jakolista / jaetut / webhookien listaus ja haku eivät lasketa. Käyntien, latausten ja toistojen kirjaus lasketaan edelleen.

## Päätepisteet

| 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` (ilman id:tä) | `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` (ilman `id`:tä) |
| `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` |
| (isännän PUT latausosoitteen luonnin jälkeen) | `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` ja `auth logout` ovat selaimen kautta kulkevia laitekirjautumisia (device flow). Ne eivät ole Unkey-reittejä.

## `GET /me`

Kirjautunut tili. `{ "userId": "...", "email": "...", "name": "..." }`. Sähköposti ja nimi jätetään pois, jos niitä ei tiedetä.

## Luo URL-linkki

```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-runko ottaa täsmälleen yhden kentistä `url`, `text` tai `storageId` sekä valinnaiset kentät `access` (`restricted` oletus \| `link` \| `public`), `slug`, `name`, `tags`, `starts`, `expires`, `maxOpenings`, `password`, `domain`, `previewName`, `previewDescription`, `previewImageStorageId`, `sticky`, `forwardParams`, `utm` (vain URL-linkit) ja `folder` (+ `folderDomain`), jos haluat luoda linkin kansion sisään. Lyhennetty muoto luo yhden variantin nimeltä `main`; ylätason `password`, `starts`, `expires` ja `maxOpenings` ovat linkin pääsyehdot. Vastaus: `{ "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }`.

`GET /links` palauttaa yhden sivun, `{ "items": [...], "cursor" }`: `?limit=` on 1-100 (oletus 50); anna edellisen sivun `?cursor=`, kunnes se on `null`. `q` vastaa kokonaisia sanoja (viimeistä etuliitteenä), ja tulokset järjestetään osuvuuden mukaan. Kohteet ovat muotoa `{ id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id }` (kansioriveillä on lisäksi `items`); `kind`-suodatin tuntee myös arvot `folder` ja `group`, `status`-suodatin arvon `mixed`, ja `folder=<slug>|root` (+ `folderDomain`) listaa yhden kansion tai ylätason. `GET /links/:id` palauttaa koko linkin kenttineen `access` ja `variants`; sisältö (`destinationUrl` / `textContent` / `fileName`) on kunkin variantin kentissä.

## Lataa tiedosto

Luo latausosoite (`{uploadUrl,storageId}`), lähetä tavut isännältä PUT-pyynnöllä ja luo sitten linkki samassa työnkulussa:

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

Pienet tiedostot voi yhä lähettää multipart-muodossa kutsulla `POST /links`:

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

Valinnaiset multipart-kentät: `access`, `slug`, `name`, `tags`, `starts` / `startsAt`, `password`, `expires`, `maxOpenings`, `domain`, `previewName`, `previewDescription`, `previewImage`.

## Päivitys, tilastot, CSV

`PATCH /links/:id` on JSON- tai multipart-pyyntö. Korvaa tiedoston tavut `storageId`:llä (`POST /uploads` + isännän PUT) tai multipart-kentällä `file` (vain yhden variantin linkit). `--status` / `{ "status": "expired" }` hylätään, joten käytä `expires`-kenttää. `{ "status": "scheduled" }` hylätään, joten käytä `starts`-kenttää. Valinnainen `maxOpenings` keskeyttää linkin, kun se on avattu niin monta kertaa; `clearMaxOpenings` poistaa rajan. `sticky` (boolean) ja `restartSplit` (boolean) ohjaavat varianttien jakoa; `forwardParams` (boolean) välittää kävijän kyselymerkkijonon eteenpäin, katso [Kyselyparametrien välitys](#forward-query-parameters). `access` määrää, kuka linkin voi avata; `resetShareLink: true` luo uuden jakolinkin. Vastaus: `{ "id", "url", "access", "status", "variantStatuses" }`.

`GET /links/:id/stats?last=24h` palauttaa kentät `visits`, `downloads`, `plays`, `visitsInLast`, `countries`, `referrers`, `variants` (varianttikohtaiset summat), `visitors` ja `crawlers` (`[{ "crawler", "company", "category", "hits", "lastSeen" }]`: botit ja linkkien esikatselut, jotka hakivat linkin; niitä ei koskaan lasketa käynneiksi; katso [Crawler-loki](https://linkdash.dev/pricing.md)).

`GET /links/export` palauttaa CSV:n sarakkeilla `slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`, yksi rivi per variantti (`folder` on sisältävän kansion slug; `access` on `restricted`, `link` tai `public`). `POST /links/import` hyväksyy raakaa CSV:tä tai multipart-kentän `file`. Rivit ryhmitellään slugin ja domainin mukaan: ensimmäinen rivi luo linkin ja sen variantin, ja seuraavat rivit lisäävät variantteja. Olemassa olevien linkkien kentät päivitetään, minkä jälkeen variantit päivitetään tai lisätään nimen perusteella. Rivit, joiden `kind` on `folder` (ja joilla on `name`), luovat kansioita, ja `folder`-sarake sijoittaa linkit paikoilleen, kun kaikki rivit on luotu. Tyhjä `access` tekee uusista linkeistä rajattuja eikä muuta olemassa olevia linkkejä.

`DELETE /links/:id` ottaa kansiolle parametrin `?contents=keep` (oletus: kohteet siirtyvät tasoa ylemmäs) tai `?contents=delete` (myös sisällä olevat kohteet ja kansiot poistetaan).

## Variantit

Jokainen linkki sisältää yhden tai useamman **variantin**. Variantilla on sisältö (`url` | `file` | `text`), omat pääsyehdot (`password`, `paused`, `starts`, `expires`, `maxOpenings`), `weight` ja valinnaiset kävijäehdot `when`. Linkille kuuluvat slug, domain, nimi, tagit, esikatselu, omat pääsyehdot (jotka ohittavat varianttien pääsyehdot), `sticky` (oletus `true`) ja `splitVersion` (jota `restartSplit` kasvattaa). Ilman `variants`-kenttää linkillä on yksi variantti nimeltä `main`. Nimet: pieniä kirjaimia, numeroita ja sisäisiä yhdysmerkkejä, 1–40 merkkiä, yksilöllinen linkin sisällä. Enintään 20 varianttia per linkki.

Kävijä saa yhden variantin. Variantit, joiden `when` täsmää, muodostavat valintajoukon (jos mikään ei täsmää, joukon muodostavat ehdottomat variantit). Joukosta tehdään painotettu valinta: pysyvä tiiviste kävijästä, linkistä ja `splitVersion`-arvosta, muuten satunnainen. Crawlerit saavat ensimmäisen aktiivisen ehdottoman variantin. Linkin `kind` on `group`, kun variantteja on useita. Linkin `status` on linkin pääsyehtojen tila, jos ne on asetettu, muuten kaikkien varianttien yhteinen tila, muuten `mixed`. `variantStatuses` laskee `{ active, paused, expired, scheduled }`.

Luo useita variantteja kerralla:

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

Jokainen variantti: `name` (pakollinen), yksi kentistä `url` | `text` | `storageId` (+ `fileName`, `fileType`, `fileSize`), `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when`. Multipart-luonti tukee vain lyhennettyä muotoa.

| Reitti | Runko | Vastaus |
| --- | --- | --- |
| `GET /links/:id/variants` | — | varianttitaulukko |
| `POST /links/:id/variants` | JSON tai multipart `file`: `name` (pakollinen), sisältö, `password`, `starts`, `expires`, `maxOpenings`, `utm`, `weight`, `when` | variantti |
| `PATCH /links/:id/variants/:name` | `name` (uudelleennimeäminen), `url`, `text`, `storageId` / `file`, `password`, `clearPassword`, `starts`, `clearStarts`, `expires`, `clearExpires`, `maxOpenings`, `clearMaxOpenings`, `status` (`active` \| `paused`), `weight`, `when`, `clearWhen`, `utm` | variantti |
| `DELETE /links/:id/variants/:name` | — | `{ "id", "variant", "deleted": true }` (viimeistä varianttia ei voi poistaa) |

`when`-avaimet (merkkijonotaulukoita; jokaisen asetetun avaimen on täsmättävä): `countries` (ISO-2), `devices` (`mobile` | `tablet` | `desktop`), `os` (`windows` | `macos` | `android` | `ios` | `linux` | `other`), `browsers` (`edge` | `chrome` | `firefox` | `safari` | `other`), `languages` (etuliite), `referrerHosts` (isäntänimen pääte).

### Kyselyparametrisäännöt

`when.params` on enintään 10 säännön taulukko, joka koskee kävijän kyselymerkkijonoa (`lida.sh/promo?src=newsletter`); jokaisen säännön on toteuduttava. Jokainen sääntö on muotoa `{ "key", "op", "value" }`, jossa `op` on jokin seuraavista: `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` on `|`-merkeillä tai pilkuilla eroteltu lista) | `exists` | `missing`. `value` on pakollinen muissa paitsi operaatioissa `exists` / `missing`. Avaimet ovat kirjainkokoherkkiä, ja arvoja verrataan täsmälleen.

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

Parametrien arvot tarkistetaan avaushetkellä, eikä niitä koskaan tallenneta analytiikkaan.

### Kyselyparametrien välitys

`forwardParams` lisää kävijän koko kyselymerkkijonon URL-varianttien perään. Se on linkin boolean-asetus (oletus `false`), jonka voi asettaa kutsuilla `POST /links` ja `PATCH /links/:id`, ja `GET /links/:id` palauttaa sen. Kävijän arvot ohittavat tallennetut arvot, myös `utm`-arvot. Tiedosto- ja tekstivariantit eivät huomioi asetusta. Kyse on reitityksestä, ei pääsynhallinnasta: kuka tahansa voi lisätä parametreja. Parametrien arvoja ei tallenneta analytiikkaan.

## Kansiot

Kansio on linkki, joka listaa siihen lisäämäsi kohteet. Katso malli sivulta [Kansiot](/fi/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_..."
```

| Reitti | Runko | Vastaus |
| --- | --- | --- |
| `POST /links` | `{ "kind": "folder", "name" }` sekä tavalliset linkkikentät; ei kenttiä `url`, `text`, `storageId` tai `variants` | luotu kansio |
| `POST /links/:id/move` | `{ "folder": "<slug>" }` tai ylätasolle `{ "folder": null }`, valinnainen `folderDomain` | `{ "id", "folder" }` |
| `POST /links/:id/copy` | — | `{ "id", "url", "access", "kind", "variants", "folder", … }` (sama käyttöoikeus, uusi jakolinkki, ei jaettuja henkilöitä) |

Siirto ja kopiointi lasketaan kumpikin yhdeksi tapahtumaksi. Tuntematon kansion slug palauttaa `404`:n (`Folder "<slug>" not found`). Jos slug ei ole kansio tai kansiota yritetään siirtää itseensä tai omaan alikansioonsa, vastaus on `400`. Kansioita voi olla sisäkkäin enintään 32 tasoa.

## Käyttöoikeudet ja jakaminen

Jokaisella linkillä ja kansiolla on `access`: `restricted` (oletus; omistaja ja ne kirjautuneet henkilöt, joille kohde on jaettu, osoitteessa `https://linkdash.dev/s/<token>`), `link` (kuka tahansa, jolla on tämä URL) tai `public` (kuka tahansa, lyhyessä URL:ssa). Aseta se kutsulla `POST /links` tai `PATCH /links/:id`. Anna `"access": "public"` linkeille, jotka on tarkoitus julkaista avoimesti. Sivulta [Jakaminen ja käyttöoikeudet](/fi/sharing) näet, miten kansiot ja katselijat toimivat.

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

| Reitti | Runko | Vastaus |
| --- | --- | --- |
| `POST /links/:id/shares` | `{ "emails": [...] }` (1–50 sähköpostiosoitetta) | `{ "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" }` (kaikki, mitä olet jakanut) |
| `GET /shared` | — | `{ "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }` |
| `DELETE /shared/:id` | — | `{ "_id", "left": true }` (`:id` on `GET /shared` -kutsun palauttama `_id` tai jakotunniste) |
| `POST /links/:id/reset-link` | — | `{ "id", "access", "url" }` |

`POST /links/:id/shares` ottaa muokkaajille arvon `"role": "editor"`. Muokkaajat voivat muuttaa kohteita ja nähdä tilastot ja tapahtumahistorian. Salasanoihin, slugiin, domainiin, käyttöoikeuksiin ja jakamiseen he eivät pääse käsiksi, eivätkä he voi poistaa, siirtää tai kopioida kohteita (`403`). Muokkaajat käyttävät `:id`:nä kohteen `_id`:tä tai jakotunnistetta. Salasanalla suojattu variantti pysyy tilassa `locked: true`, kunnes kutsutaan `POST /links/:id/unlock` (avaus kestää 30 minuuttia; kymmenen väärää salasanaa tunnissa, sitten `429`). Jos tallennat sen jälkeen, kun joku muu on jo tallentanut, vastaus on `409` vain silloin, kun pyyntö lähettää `expectedVersion`-kentän. Kaikki jakoreitit ottavat `?domain=`-parametrin, kun sama slug on käytössä useammalla domainilla. `accepted` on `false`, kunnes kyseisellä sähköpostiosoitteella on vahvistettu tili; `viaFolder` tarkoittaa, että käyttöoikeus tulee ylemmästä kansiosta. Enintään 200 henkilöä per kohde ja 100 kutsusähköpostia per tili päivässä. `GET /shares` ja `GET /shared` palauttavat sivun kerrallaan: `?limit=` on 1-100 (oletus 50); anna edellisen sivun `?cursor=`, kunnes `cursor` on `null`. Jakaminen, jaon poisto ja nollaus lasketaan kukin yhdeksi tapahtumaksi, poistuminen ei. Ylemmän jaetun kansion kautta saatu käyttöoikeus säilyy poistumisen jälkeen.

## Virheet

| Tila | Milloin |
| --- | --- |
| 400 | Validointivirhe, puuttuva runko, sekoitetut luontityypit |
| 401 | Puuttuva tai virheellinen bearer-avain |
| 404 | Tuntematon slug, domain tai kansio |
| 409 | Slug varattu (`code: "slug_taken"`) |
| 429 | Kuukausittainen tapahtumakiintiö täynnä |
| 503 | API-avaimia ei ole määritetty tässä käyttöönotossa |

Näiden päätepisteiden tiedot löydät sivuilta [webhookit](/fi/webhooks) ja [omat domainit](/fi/domains).
