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. Τα μικρά αρχεία μπορούν ακόμη να χρησιμοποιούν multipartfileστοPOST /links. - Διάρκειες:
7d,24h,30m,1wή ημερομηνία ISO. Πεδία:expires/expiresAt,starts/startsAt. - Όριο ανοιγμάτων: προαιρετικός θετικός ακέραιος
maxOpenings. Το link τίθεται σε παύση μετά από τόσα επιτυχημένα ανοίγματα. Αυξήστε τοmaxOpeningsή χρησιμοποιήστε τοclearMaxOpeningsγια να εξυπηρετείται ξανά. Παραλείψτε τοmaxOpeningsγια απεριόριστα ανοίγματα. - Αν ένα slug υπάρχει σε δύο domains του ιδιοκτήτη, περάστε
?domain=/ JSONdomain. - Σφάλματα:
{ "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 παραλείπονται όταν δεν είναι γνωστά.
Δημιουργία URL link
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.

