HTTP-rajapinta
REST-rajapinta osoitteessa https://api.linkdash.dev/v1, todennus hallintapaneelista saatavalla bearer-avaimella. Samat toiminnot kuin CLI:ssä ja MCP:ssä.
Perus-URL: https://api.linkdash.dev/v1
Todennus: Authorization: Bearer ldash_... (luo avaimet kohdassa Hallintapaneeli → API-avaimet). Älä keksi avaimia itse.
CLI-viite: CLI. MCP: MCP. Hinnoittelu / kiintiöt: Hinnoittelu. Löytäminen (ei todennusta): GET https://api.linkdash.dev/v1. Pelkkä markdown: api.md.
Julkiset tunnisteet ovat slugeja (deck, k3m9xq), eivät Convexin _id-arvoja. JSON-kenttien nimet vastaavat CLI 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,texttaistorageId(POST /uploads-kutsun jälkeen), taivariants-taulukon (katso Variantit), tai"kind": "folder"yhdessäname-kentän kanssa (katso Kansiot). Latausosoitteen luonti palauttaa{ "uploadUrl", "storageId" }. Isäntä lähettää tavut PUT-pyynnöllä osoitteeseenuploadUrl. Pienet tiedostot voi yhä lähettää multipart-kentässäfilekutsullaPOST /links. - Kestot:
7d,24h,30m,1wtai 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. NostamaxOpenings-arvoa tai käytäclearMaxOpenings-kenttää, niin linkki toimii taas. JätämaxOpeningspois, jos et halua rajaa. - Jos sama slug on käytössä kahdella omistajan domainilla, anna
?domain=/ JSON-kenttädomain. - Virheet:
{ "error": "..." }sekä valinnainencode. Varatutlida.sh-slugit palauttavat409jacode: "slug_taken". - Käyttöoikeus: uudet linkit ja kansiot ovat
restricted, ellei rungossa asetetaaccess-kenttää (katso Käyttöoikeudet ja jakaminen). Vastauksissaurlon 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) |
PATCH /links/:id/shares/:email |
{ "role": "viewer" | "editor" } |
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) |
|
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
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:
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:
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 (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. 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).
GET /links/export palauttaa CSV 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 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:
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.
{ "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.
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 (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). Aseta se kutsulla POST /links tai PATCH /links/:id. Anna "access": "public" linkeille, jotka on tarkoitus julkaista avoimesti. Sivulta Jakaminen ja käyttöoikeudet näet, miten kansiot ja katselijat toimivat.
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 kohteen _id 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 ja omat domainit.

