HTTP API
REST adresē https://api.linkdash.dev/v1 ar bearer atslēgu no informācijas paneļa. Tās pašas darbības kā CLI un MCP.
Bāzes URL: https://api.linkdash.dev/v1
Autentifikācija: Authorization: Bearer ldash_... (atslēgas izveidojiet sadaļā Informācijas panelis → API atslēgas). Neizdomājiet atslēgas.
CLI dokumentācija: CLI. MCP: MCP. Cenas / kvotas: Cenas. Atklāšana (bez autentifikācijas): GET https://api.linkdash.dev/v1. Vienkāršs markdown: api.md.
Publiskie identifikatori ir slug vērtības (deck, k3m9xq), nevis Convex _id. JSON lauku nosaukumi atbilst CLI stdout (id, url, kind, …).
Konvencijas
- JSON
Content-Type: application/json, ja nav norādīts citādi. - Izveidei jānorāda tieši viens no
url,textvaistorageId(pēcPOST /uploads), vaivariantsmasīvs (skatiet Varianti), vai"kind": "folder"kopā arname(skatiet Mapes). Izsniegšanas pieprasījums atgriež{ "uploadUrl", "storageId" }. Resursdators nosūta baitus uzuploadUrlar PUT. Mazi faili joprojām var izmantot multipart laukufilepieprasījumāPOST /links. - Ilgumi:
7d,24h,30m,1wvai ISO datums. Lauki:expires/expiresAt,starts/startsAt. - Atvēršanu ierobežojums: neobligāts pozitīvs vesels skaitlis
maxOpenings. Saite tiek apturēta pēc tik daudzām veiksmīgām atvēršanām. PalielinietmaxOpeningsvai izmantojietclearMaxOpenings, lai saite atkal būtu pieejama. Lai atvēršanu skaits nebūtu ierobežots, izlaidietmaxOpenings. - Ja slug vērtība pastāv divos īpašnieka domēnos, nododiet
?domain=/ JSONdomain. - Kļūdas:
{ "error": "..." }un neobligātscode. Aizņemtaslida.shslug vērtības atgriež409arcode: "slug_taken". - Piekļuve: jaunas saites un mapes ir
restricted, ja vien pieprasījuma pamattekstā nav iestatītsaccess(skatiet Piekļuve un kopīgošana).urlatbildēs ir kopīgošanas URL (https://linkdash.dev/s/<token>), ja vien saite nav publiska — tad tas ir īsais URL. - Rakstīšanas darbības tiek ieskaitītas mēneša notikumu kvotā (ieskaitot kopīgošanu, kopīgošanas atcelšanu un atiestatīšanu). Saraksta / iegūšanas / statistikas / eksporta / kopīgojumu saraksta / kopīgoto elementu / webhook saraksta/iegūšanas pieprasījumi netiek ieskaitīti. Apmeklējumu / lejupielāžu / atskaņojumu reģistrēšana joprojām tiek ieskaitīta.
Galapunkti
| 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 (bez 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 (bez 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 |
| (resursdatora PUT pēc izsniegšanas) | 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 un auth logout ir pārlūka ierīces plūsmas. Tie nav Unkey maršruti.
GET /me
Konts, kurā esat pierakstījies. { "userId": "...", "email": "...", "name": "..." }. E-pasts un vārds tiek izlaisti, ja tie nav zināmi.
URL saites izveide
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 pamatteksts pieņem tieši vienu no url, text vai storageId, kā arī neobligātos laukus access (restricted pēc noklusējuma | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (tikai URL saitēm) un folder (+ folderDomain), lai izveidotu saiti mapē. Saīsinātā forma izveido vienu variantu ar nosaukumu main; augšējā līmeņa password, starts, expires un maxOpenings ir saites ierobežojumi. Atbilde: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.
GET /links atgriež vienu lapu, { "items": [...], "cursor" }: ?limit= ir 1-100 (noklusējums 50); nododiet ?cursor= no iepriekšējās lapas, līdz tas ir null. q atbilst veseliem vārdiem (pēdējais — kā prefikss), rezultāti sakārtoti pēc atbilstības. Elementi ir { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (mapju rindas papildus satur items); kind filtrs papildus pieļauj folder un group, status filtrs papildus pieļauj mixed, un folder=<slug>|root (+ folderDomain) uzskaita vienas mapes saturu vai augšējo līmeni. GET /links/:id atgriež pilnu saiti ar access un variants; saturs (destinationUrl / textContent / fileName) atrodas katrā variantā.
Faila augšupielāde
Izsniedziet augšupielādes URL ({uploadUrl,storageId}), nosūtiet baitus no resursdatora ar PUT un pēc tam tajā pašā plūsmā izveidojiet saiti:
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}'
Mazi faili joprojām var izmantot multipart pieprasījumā POST /links:
curl https://api.linkdash.dev/v1/links \
-H "Authorization: Bearer ldash_..." \
-F "file=@./deck.pdf" \
-F "expires=7d" \
-F "slug=deck"
Neobligātie multipart lauki: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.
Atjaunināšana, statistika, CSV
PATCH /links/:id pieņem JSON vai multipart. Aizstājiet faila baitus ar storageId pēc POST /uploads + resursdatora PUT vai ar multipart lauku file (tikai saitēm ar vienu variantu). --status / { "status": "expired" } tiek noraidīts — izmantojiet expires. { "status": "scheduled" } tiek noraidīts — izmantojiet starts. Neobligātais maxOpenings aptur saiti pēc tik daudzām atvēršanām; clearMaxOpenings noņem ierobežojumu. sticky (boolean) un restartSplit (boolean) kontrolē variantu piešķiršanu; forwardParams (boolean) pārsūta apmeklētāja vaicājuma virkni, skatiet Vaicājuma parametru pārsūtīšana. access nosaka, kas var saiti atvērt; resetShareLink: true izsniedz jaunu kopīgošanas URL. Atbilde: { "id", "url", "access", "status", "variantStatuses" }.
GET /links/:id/stats?last=24h atgriež visits, downloads, plays, visitsInLast, countries, referrers, variants (kopsummas katram variantam), visitors un crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: roboti un saišu priekšskatījumi, kas ielādēja saiti; tie nekad netiek skaitīti kā apmeklējumi; skatiet Rāpuļprogrammu žurnāls).
GET /links/export ir CSV ar kolonnām slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, viena rinda katram variantam (folder ir saturošās mapes slug vērtība; access ir restricted, link vai public). POST /links/import pieņem neapstrādātu CSV vai multipart file; rindas tiek grupētas pēc slug + domēna (pirmā rinda izveido saiti ar tās variantu, nākamās rindas pievieno variantus; esošajām saitēm tiek atjaunināti lauki, pēc tam varianti tiek atjaunināti vai pievienoti pēc nosaukuma). Rindas ar kind folder (ar name) izveido mapes, un kolonna folder izvieto saites pēc tam, kad visas rindas ir izveidotas. Tukšs access padara jaunas saites ierobežotas un atstāj esošās saites nemainītas.
DELETE /links/:id mapei pieņem ?contents=keep (noklusējums: elementi tiek pārvietoti vienu līmeni augstāk) vai ?contents=delete (tiek dzēsti arī tajā esošie elementi un mapes).
Varianti
Katra saite ir viena vai vairāku variantu konteiners: saturs (url | file | text) un savi ierobežojumi (password, paused, starts, expires, maxOpenings), weight un neobligāti apmeklētāja nosacījumi when. Saitei pieder slug, domēns, nosaukums, tagi, priekšskatījums, savi ierobežojumi (kuriem ir prioritāte pār variantu ierobežojumiem), sticky (noklusējums true) un splitVersion (to palielina restartSplit). Bez variants saitei ir viens variants ar nosaukumu main. Nosaukumi: mazie burti, cipari, iekšējas defises, 1–40 rakstzīmes, unikāli katras saites ietvaros. Ne vairāk kā 20 varianti vienai saitei.
Apmeklētājs saņem vienu variantu: varianti, kuru when atbilst, veido kopu (ja neviens neatbilst, kopu veido beznosacījuma varianti), pēc tam notiek svērta izvēle (noturīgs jaucējs no apmeklētāja + saites + splitVersion, citādi nejauša). Rāpuļprogrammas saņem pirmo aktīvo beznosacījuma variantu. Saites kind ir group, ja tai ir vairāki varianti. Saites status ir saites ierobežojumu statuss, ja tie ir iestatīti, citādi visiem variantiem kopīgais statuss, citādi mixed. variantStatuses uzskaita { active, paused, expired, scheduled }.
Izveidojiet vairākus variantus uzreiz:
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"]}}]}'
Katrs variants: name (obligāts), viens no url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Multipart izveide atbalsta tikai saīsināto formu.
| Maršruts | Pamatteksts | Atbilde |
|---|---|---|
GET /links/:id/variants |
— | variantu masīvs |
POST /links/:id/variants |
JSON vai multipart file: name (obligāts), saturs, password, starts, expires, maxOpenings, utm, weight, when |
variants |
PATCH /links/:id/variants/:name |
name (pārdēvēšana), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm |
variants |
DELETE /links/:id/variants/:name |
— | { "id", "variant", "deleted": true } (pēdējo variantu nevar dzēst) |
when atslēgas (virkņu masīvi; katrai iestatītajai atslēgai jāatbilst): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (prefikss), referrerHosts (resursdatora nosaukuma sufikss).
Vaicājuma parametru noteikumi
when.params ir masīvs ar līdz 10 noteikumiem par apmeklētāja vaicājuma virkni (lida.sh/promo?src=newsletter); jāizpildās katram noteikumam. Katrs noteikums ir { "key", "op", "value" }, kur op ir viens no equals | notEquals | includes | startsWith | endsWith | in (value ir ar | vai komatu atdalīts saraksts) | exists | missing. value ir obligāts, izņemot exists / missing. Atslēgas ir reģistrjutīgas, vērtības tiek salīdzinātas precīzi.
{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }
Parametru vērtības tiek salīdzinātas atvēršanas brīdī un nekad netiek saglabātas analītikā.
Vaicājuma parametru pārsūtīšana
forwardParams (saites boolean vērtība, noklusējums false; iestatāms ar POST /links un PATCH /links/:id, atgriež GET /links/:id) pievieno visu apmeklētāja vaicājuma virkni URL variantiem. Apmeklētāja vērtības aizstāj saglabātās, ieskaitot utm. Failu un teksta varianti to ignorē. Tā ir maršrutēšana, nevis piekļuves kontrole: parametrus var pievienot ikviens. Parametru vērtības netiek saglabātas analītikā.
Mapes
Mape ir saite, kas uzskaita tajā ievietotos elementus. Modeļa aprakstu skatiet sadaļā Mapes.
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_..."
| Maršruts | Pamatteksts | Atbilde |
|---|---|---|
POST /links |
{ "kind": "folder", "name" } un parastie saites lauki; bez url, text, storageId vai variants |
izveidotā mape |
POST /links/:id/move |
{ "folder": "<slug>" } vai { "folder": null } augšējam līmenim, neobligāts folderDomain |
{ "id", "folder" } |
POST /links/:id/copy |
— | { "id", "url", "access", "kind", "variants", "folder", … } (tāda pati piekļuve, jauns kopīgošanas URL, bez personām) |
Pārvietošana un kopēšana katra tiek ieskaitīta kā viens notikums. Nezināma mapes slug vērtība atgriež 404 (Folder "<slug>" not found); slug vērtība, kas nav mape, vai mapes pārvietošana pašā sevī vai kādā no tās apakšmapēm atgriež 400. Mapes var būt ligzdotas ne vairāk kā 32 līmeņu dziļumā.
Piekļuve un kopīgošana
Katrai saitei un mapei ir access: restricted (noklusējums; īpašnieks un pierakstījušās personas, ar kurām tā ir kopīgota, adresē https://linkdash.dev/s/<token>), link (ikviens, kam ir šis URL) vai public (ikviens, izmantojot īso URL). Iestatiet to ar POST /links vai PATCH /links/:id. Saitēm, kas paredzētas publiskai publicēšanai, nododiet "access": "public". Kā darbojas mapes un skatītāji, skatiet sadaļā Kopīgošana un piekļuve.
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_..."
| Maršruts | Pamatteksts | Atbilde |
|---|---|---|
POST /links/:id/shares |
{ "emails": [...] } (1–50 e-pasta adreses) |
{ "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" } (viss, ko esat kopīgojuši) |
GET /shared |
— | { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" } |
DELETE /shared/:id |
— | { "_id", "left": true } (:id ir _id vai kopīgošanas marķieris no GET /shared) |
POST /links/:id/reset-link |
— | { "id", "access", "url" } |
Lai pievienotu redaktorus, POST /links/:id/shares pieņem "role": "editor". Redaktori var mainīt elementus un redzēt statistiku un aktivitāti, bet nekad nevar mainīt paroles, slug, domēnu, piekļuvi vai kopīgošanu, kā arī dzēst, pārvietot vai kopēt (403); kā :id viņi izmanto elementa _id vai kopīgošanas marķieri, un ar paroli aizsargāts variants paliek locked: true, līdz tiek izsaukts POST /links/:id/unlock (30 minūtes, desmit nepareizas paroles stundā, pēc tam 429). Saglabāšana pēc tam, kad kāds cits jau ir saglabājis izmaiņas, atgriež 409 tikai tad, ja pieprasījumā ir nosūtīts expectedVersion. Visi kopīgošanas maršruti pieņem ?domain=, ja slug vērtība atkārtojas. accepted ir false, līdz šai e-pasta adresei ir verificēts konts; viaFolder nozīmē, ka piekļuve ir iegūta no augstāk esošas mapes. Līdz 200 personām vienam elementam un 100 uzaicinājuma e-pastiem vienam kontam dienā. GET /shares un GET /shared atgriež pa vienai lapai: ?limit= ir 1-100 (noklusējums 50); nododiet ?cursor= no iepriekšējās lapas, līdz cursor ir null. Kopīgošana, kopīgošanas atcelšana un atiestatīšana katra tiek ieskaitīta kā viens notikums; aiziešana netiek ieskaitīta. Piekļuve, kas iegūta caur augstāk esošu kopīgotu mapi, saglabājas arī pēc aiziešanas.
Kļūdas
| Statuss | Kad |
|---|---|
| 400 | Validācijas kļūda, trūkst pamatteksta, jaukti izveides veidi |
| 401 | Trūkst bearer atslēgas vai tā ir nederīga |
| 404 | Nezināma slug vērtība, domēns vai mape |
| 409 | Slug vērtība ir aizņemta (code: "slug_taken") |
| 429 | Sasniegta mēneša notikumu kvota |
| 503 | Šajā izvietojumā nav konfigurētas API atslēgas |
Šo galapunktu aprakstu skatiet sadaļās tīmekļa āķi un pielāgoti domēni.

