Μετάβαση στο περιεχόμενο
LinkdashLinkdash
Ελληνικά
Esc
↑↓πλοήγηση↵άνοιγμα⌘Jπροεπισκόπηση
Σε αυτή τη σελίδα

HTTP API

REST στο https://api.linkdash.dev/v1 με bearer key από το dashboard. Οι ίδιες λειτουργίες με το CLI και το MCP.

Base URL: https://api.linkdash.dev/v1

Πιστοποίηση: Authorization: Bearer ldash_... (δημιουργήστε κλειδιά στο Πίνακας ελέγχου → Κλειδιά API). Μην επινοείτε κλειδιά.

Αναφορά CLI: CLI. MCP: MCP. Τιμολόγηση / όρια: Τιμολόγηση. Discovery (χωρίς πιστοποίηση): GET https://api.linkdash.dev/v1. Απλό markdown: api.md.

Τα δημόσια id είναι slugs (deck, k3m9xq), όχι το _id του Convex. Τα ονόματα πεδίων JSON ταυτίζονται με το stdout του CLI (id, url, kind, …).

Συμβάσεις

  • JSON Content-Type: application/json, εκτός αν αναφέρεται διαφορετικά.
  • Η δημιουργία δέχεται ακριβώς ένα από τα url, text ή storageId (μετά από POST /uploads), ή έναν πίνακα variants (δείτε Variants), ή "kind": "folder" με name (δείτε Φάκελοι). Το mint επιστρέφει { "uploadUrl", "storageId" }. Ο host κάνει PUT τα bytes στο uploadUrl. Τα μικρά αρχεία μπορούν ακόμη να χρησιμοποιούν multipart file στο POST /links.
  • Διάρκειες: 7d, 24h, 30m, 1w ή ημερομηνία ISO. Πεδία: expires / expiresAt, starts / startsAt.
  • Όριο ανοιγμάτων: προαιρετικός θετικός ακέραιος maxOpenings. Το link τίθεται σε παύση μετά από τόσα επιτυχημένα ανοίγματα. Αυξήστε το maxOpenings ή χρησιμοποιήστε το clearMaxOpenings για να εξυπηρετείται ξανά. Παραλείψτε το maxOpenings για απεριόριστα ανοίγματα.
  • Αν ένα slug υπάρχει σε δύο domains του ιδιοκτήτη, περάστε ?domain= / JSON domain.
  • Σφάλματα: { "error": "..." } συν προαιρετικό code. Τα κατειλημμένα slugs στο lida.sh επιστρέφουν 409 με code: "slug_taken".
  • Πρόσβαση: τα νέα links και οι νέοι φάκελοι είναι restricted, εκτός αν το body ορίζει access (δείτε Πρόσβαση και κοινοποίηση). Το url στις αποκρίσεις είναι το share URL (https://linkdash.dev/s/<token>), εκτός αν το link είναι δημόσιο, οπότε είναι το short URL.
  • Οι εγγραφές μετρούν στο μηνιαίο όριο events (συμπεριλαμβάνονται τα share, unshare και reset). Τα list / get / stats / export / shares list / shared / webhook list/get δεν μετρούν. Το ingest των visit / download / play εξακολουθεί να μετράει.

Endpoints

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) 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 (χωρίς 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
(PUT από τον host μετά το mint) 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 και auth logout είναι browser device flows. Δεν είναι routes του Unkey.

GET /me

Ο συνδεδεμένος λογαριασμός. { "userId": "...", "email": "...", "name": "..." }. Τα email και name παραλείπονται όταν δεν είναι γνωστά.

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 body δέχεται ακριβώς ένα από τα url, text ή storageId, συν τα προαιρετικά access (restricted προεπιλογή | link | public), slug, name, tags, starts, expires, maxOpenings, password, domain, previewName, previewDescription, previewImageStorageId, sticky, forwardParams, utm (μόνο για URL links) και folder (+ folderDomain) για δημιουργία μέσα σε φάκελο. Η σύντομη μορφή δημιουργεί μία variant με όνομα main· τα password, starts, expires και maxOpenings στο ανώτατο επίπεδο αποτελούν το gate του link. Απόκριση: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }.

Το GET /links επιστρέφει μία σελίδα, { "items": [...], "cursor" }: το ?limit= είναι 1-100 (προεπιλογή 50)· περάστε το ?cursor= από την προηγούμενη σελίδα μέχρι να γίνει null. Το q ταιριάζει ολόκληρες λέξεις (την τελευταία ως πρόθεμα), με ταξινόμηση κατά συνάφεια. Τα items είναι { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } (οι γραμμές φακέλων προσθέτουν items)· το φίλτρο kind προσθέτει τα folder και group, το φίλτρο status προσθέτει το mixed, και το folder=<slug>|root (+ folderDomain) εμφανίζει έναν φάκελο ή το ανώτατο επίπεδο. Το GET /links/:id επιστρέφει ολόκληρο το link με access και variants· το περιεχόμενο (destinationUrl / textContent / fileName) βρίσκεται σε κάθε variant.

Ανέβασμα αρχείου

Κάντε mint ένα upload URL ({uploadUrl,storageId}), κάντε PUT τα bytes από τον host και, στη συνέχεια, δημιουργήστε το link στην ίδια ροή:

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

Τα μικρά αρχεία μπορούν ακόμη να χρησιμοποιούν multipart στο POST /links:

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

Προαιρετικά πεδία multipart: access, slug, name, tags, starts / startsAt, password, expires, maxOpenings, domain, previewName, previewDescription, previewImage.

Ενημέρωση, στατιστικά, CSV

Το PATCH /links/:id δέχεται JSON ή multipart. Αντικαταστήστε τα bytes του αρχείου με storageId μετά από POST /uploads + PUT από τον host ή με το πεδίο multipart file (μόνο για links με μία variant). Το --status / { "status": "expired" } απορρίπτεται — χρησιμοποιήστε το expires. Το { "status": "scheduled" } απορρίπτεται — χρησιμοποιήστε το starts. Το προαιρετικό maxOpenings θέτει το link σε παύση μετά από τόσα ανοίγματα· το clearMaxOpenings αφαιρεί το όριο. Τα sticky (boolean) και restartSplit (boolean) ελέγχουν την ανάθεση variants· το forwardParams (boolean) προωθεί το query string του επισκέπτη, δείτε Προώθηση query parameters. Το access αλλάζει ποιος μπορεί να το ανοίξει· το resetShareLink: true εκδίδει νέο share URL. Απόκριση: { "id", "url", "access", "status", "variantStatuses" }.

Το GET /links/:id/stats?last=24h επιστρέφει visits, downloads, plays, visitsInLast, countries, referrers, variants (σύνολα ανά variant), visitors και crawlers ([{ "crawler", "company", "category", "hits", "lastSeen" }]: bots και link previews που ανέκτησαν το link, τα οποία δεν μετρούν ποτέ ως επισκέψεις· δείτε Αρχείο crawlers).

Το GET /links/export είναι CSV με στήλες slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access, μία γραμμή ανά variant (το folder είναι το slug του φακέλου που το περιέχει· το access είναι restricted, link ή public). Το POST /links/import δέχεται raw CSV ή multipart file· οι γραμμές ομαδοποιούνται κατά slug + domain (η πρώτη γραμμή δημιουργεί το link με τη variant του, οι επόμενες γραμμές προσθέτουν variants· στα υπάρχοντα links ενημερώνονται τα πεδία και, στη συνέχεια, ενημερώνονται ή προστίθενται variants κατά όνομα). Οι γραμμές με kind folder (με name) δημιουργούν φακέλους, και η στήλη folder τοποθετεί τα links αφού υπάρξουν όλες οι γραμμές. Ένα κενό access κάνει τα νέα links restricted και αφήνει τα υπάρχοντα links ως έχουν.

Το DELETE /links/:id σε φάκελο δέχεται ?contents=keep (προεπιλογή: τα items μετακινούνται ένα επίπεδο πάνω) ή ?contents=delete (διαγράφονται επίσης τα items και οι φάκελοι που περιέχει).

Variants

Κάθε link είναι ένας container μίας ή περισσότερων variants: περιεχόμενο (url | file | text) συν το δικό της gate (password, paused, starts, expires, maxOpenings), ένα weight και προαιρετικές συνθήκες επισκέπτη when. Στο link ανήκουν τα slug, domain, name, tags, preview, το δικό του gate (το οποίο υπερισχύει των gates των variants), το sticky (προεπιλογή true) και το splitVersion (αυξάνεται με το restartSplit). Χωρίς variants, ένα link έχει μία variant με όνομα main. Ονόματα: πεζά γράμματα, ψηφία, ενδιάμεσες παύλες, 1–40 χαρακτήρες, μοναδικά ανά link. Έως 20 variants ανά link.

Κάθε επισκέπτης λαμβάνει μία variant: οι variants των οποίων το when ταιριάζει σχηματίζουν το pool (αν καμία δεν ταιριάζει, το σχηματίζουν οι variants χωρίς συνθήκες) και ακολουθεί σταθμισμένη επιλογή (sticky hash του επισκέπτη + link + splitVersion, διαφορετικά τυχαία). Οι crawlers λαμβάνουν την πρώτη ενεργή variant χωρίς συνθήκες. Το kind του link είναι group όταν υπάρχουν πολλές variants. Το status του link είναι το gate του link όταν έχει οριστεί, διαφορετικά το status που μοιράζονται όλες οι variants, διαφορετικά mixed. Το variantStatuses μετράει { active, paused, expired, scheduled }.

Δημιουργήστε πολλές variants ταυτόχρονα:

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

Κάθε variant: name (υποχρεωτικό), ένα από τα url | text | storageId (+ fileName, fileType, fileSize), password, starts, expires, maxOpenings, utm, weight, when. Η δημιουργία μέσω multipart υποστηρίζει μόνο τη σύντομη μορφή.

Route Body Απόκριση
GET /links/:id/variants — πίνακας variants
POST /links/:id/variants JSON ή multipart file: name (υποχρεωτικό), περιεχόμενο, password, starts, expires, maxOpenings, utm, weight, when η variant
PATCH /links/:id/variants/:name name (μετονομασία), url, text, storageId / file, password, clearPassword, starts, clearStarts, expires, clearExpires, maxOpenings, clearMaxOpenings, status (active | paused), weight, when, clearWhen, utm η variant
DELETE /links/:id/variants/:name — { "id", "variant", "deleted": true } (η τελευταία variant δεν μπορεί να διαγραφεί)

Κλειδιά του when (πίνακες από strings· κάθε κλειδί που ορίζεται πρέπει να ταιριάζει): countries (ISO-2), devices (mobile | tablet | desktop), os (windows | macos | android | ios | linux | other), browsers (edge | chrome | firefox | safari | other), languages (πρόθεμα), referrerHosts (επίθημα host).

Κανόνες query parameters

Το when.params είναι ένας πίνακας έως 10 κανόνων για το query string του επισκέπτη (lida.sh/promo?src=newsletter)· κάθε κανόνας πρέπει να ισχύει. Κάθε κανόνας είναι { "key", "op", "value" } με op ένα από τα equals | notEquals | includes | startsWith | endsWith | in (το value είναι λίστα διαχωρισμένη με | ή κόμμα) | exists | missing. Το value είναι υποχρεωτικό, εκτός από τα exists / missing. Τα κλειδιά κάνουν διάκριση πεζών-κεφαλαίων και οι τιμές συγκρίνονται ακριβώς.

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

Οι τιμές των parameters ελέγχονται κατά το άνοιγμα και δεν αποθηκεύονται ποτέ στα analytics.

Προώθηση query parameters

Το forwardParams (boolean στο link, προεπιλογή false· ορίζεται στα POST /links και PATCH /links/:id και επιστρέφεται από το GET /links/:id) προσαρτά ολόκληρο το query string του επισκέπτη στις URL variants. Οι τιμές του επισκέπτη υπερισχύουν των αποθηκευμένων, συμπεριλαμβανομένου του utm. Οι variants αρχείου και κειμένου το αγνοούν. Πρόκειται για δρομολόγηση, όχι για έλεγχο πρόσβασης: οποιοσδήποτε μπορεί να προσθέσει parameters. Οι τιμές των parameters δεν αποθηκεύονται στα analytics.

Φάκελοι

Ένας φάκελος είναι ένα link που εμφανίζει τα items που τοποθετείτε σε αυτόν. Δείτε Φάκελοι για το μοντέλο.

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_..."
Route Body Απόκριση
POST /links { "kind": "folder", "name" } συν τα συνήθη πεδία link· χωρίς url, text, storageId ή variants ο φάκελος που δημιουργήθηκε
POST /links/:id/move { "folder": "<slug>" } ή { "folder": null } για το ανώτατο επίπεδο, προαιρετικό folderDomain { "id", "folder" }
POST /links/:id/copy — { "id", "url", "access", "kind", "variants", "folder", … } (ίδια πρόσβαση, νέο share URL, χωρίς άτομα)

Η μετακίνηση και η αντιγραφή μετρούν η καθεμία ως ένα event. Ένα άγνωστο slug φακέλου επιστρέφει 404 (Folder "<slug>" not found)· ένα slug που δεν είναι φάκελος, ή η μετακίνηση ενός φακέλου μέσα στον εαυτό του ή σε φάκελο κάτω από αυτόν, επιστρέφει 400. Οι φάκελοι εμφωλεύονται έως 32 επίπεδα βάθος.

Πρόσβαση και κοινοποίηση

Κάθε link και φάκελος έχει access: restricted (προεπιλογή· ο ιδιοκτήτης και τα άτομα με τα οποία έχει κοινοποιηθεί, συνδεδεμένα, στο https://linkdash.dev/s/<token>), link (οποιοσδήποτε έχει αυτό το URL) ή public (οποιοσδήποτε, στο short URL). Ορίστε το στο POST /links ή στο PATCH /links/:id. Περάστε "access": "public" για links που προορίζονται για δημόσια ανάρτηση. Δείτε Κοινοποίηση και πρόσβαση για το πώς λειτουργούν οι φάκελοι και οι viewers.

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_..."
Route Body Απόκριση
POST /links/:id/shares { "emails": [...] } (1–50 email) { "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" } (όλα όσα έχετε κοινοποιήσει)
GET /shared — { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }
DELETE /shared/:id — { "_id", "left": true } (το :id είναι το _id ή το share token από το GET /shared)
POST /links/:id/reset-link — { "id", "access", "url" }

Το POST /links/:id/shares δέχεται "role": "editor" για editors. Οι editors αλλάζουν items και βλέπουν στατιστικά και δραστηριότητα, αλλά ποτέ κωδικούς πρόσβασης, slug, domain, access, κοινοποίηση, διαγραφή, μετακίνηση ή αντιγραφή (403)· χρησιμοποιούν το _id του item ή το share token ως :id, και μια variant με κωδικό πρόσβασης παραμένει locked: true μέχρι το POST /links/:id/unlock (30 λεπτά, δέκα λανθασμένοι κωδικοί ανά ώρα, έπειτα 429). Η αποθήκευση αφού κάποιος άλλος έχει ήδη αποθηκεύσει επιστρέφει 409 μόνο όταν το αίτημα στέλνει expectedVersion. Όλα τα share routes δέχονται ?domain= όταν το slug επαναλαμβάνεται. Το accepted είναι false μέχρι το συγκεκριμένο email να αποκτήσει επαληθευμένο λογαριασμό· το viaFolder σημαίνει ότι η πρόσβαση προέρχεται από έναν φάκελο πιο πάνω. Έως 200 άτομα ανά item και 100 email προσκλήσεων ανά λογαριασμό ανά ημέρα. Τα GET /shares και GET /shared επιστρέφουν μία σελίδα κάθε φορά: το ?limit= είναι 1-100 (προεπιλογή 50)· περάστε το ?cursor= από την προηγούμενη σελίδα μέχρι το cursor να γίνει null. Τα share, unshare και reset μετρούν το καθένα ως ένα event· η αποχώρηση όχι. Η πρόσβαση μέσω ενός κοινόχρηστου φακέλου πιο πάνω παραμένει μετά την αποχώρηση.

Σφάλματα

Status Πότε
400 Validation, λείπει το body, μεικτοί τύποι δημιουργίας
401 Λείπει ή είναι άκυρο το bearer key
404 Άγνωστο slug, domain ή φάκελος
409 Το slug είναι κατειλημμένο (code: "slug_taken")
429 Συμπληρώθηκε το μηνιαίο όριο events
503 Τα API keys δεν έχουν ρυθμιστεί σε αυτό το deployment

Δείτε webhooks και custom domains για αυτά τα endpoints.

Σας φάνηκε χρήσιμη αυτή η σελίδα;