Siirry sisältöön
LinkdashLinkdash
Suomi
Esc
↑↓siirry↵avaa⌘Jesikatselu
Tällä sivulla

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, text tai storageId (POST /uploads -kutsun jälkeen), tai variants-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ä 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 ja code: "slug_taken".
  • Käyttöoikeus: uudet linkit ja kansiot ovat restricted, ellei rungossa aseteta access-kenttää (katso Käyttöoikeudet ja jakaminen). 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) 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.

Oliko tästä sivusta apua?