Dokumentacja API
Wysyłaj pliki z własnych narzędzi (skrypty, programy, serwery): utwórz transfer, prześlij pliki w częściach, odbierz link.
Klucz dostępny w planach Pro i Business, w Moje konto › API. Cennik
Uwierzytelnianie
Utwórz klucz w Moje konto › API i wysyłaj go w nagłówku Authorization każdego żądania. Zachowaj go w tajemnicy: daje dostęp do twoich transferów. Usunięty klucz natychmiast przestaje działać.
Authorization: Bearer mlk_…Jeśli Twoje narzędzie lub hosting nie przekazuje nagłówka Authorization, wyślij ten sam klucz w nagłówku X-API-Key:
X-API-Key: mlk_…120 żądań na minutę na klucz. Rozmiar, liczba plików i czas dostępności: zgodnie z twoim planem.
Wysyłanie plików w trzech krokach
1. Utwórz transfer
Podaj listę plików (nazwa i rozmiar w bajtach). Z „recipients” każdy odbiorca dostaje e-mail; bez odbiorców otrzymujesz link do udostępnienia. Opcjonalnie: „message”, „password”, „expire_days”, „delete_after_download”.
curl -X POST https://misi.link/api/v1/transfers \
-H "Authorization: Bearer $MISILINK_KEY" -H "Content-Type: application/json" \
-d '{"files": [{"name": "film.mov", "size": 5368709120}],
"recipients": ["client@example.com"], "message": "…", "expire_days": 14}'{"ok": true, "id": "aB3dE5fG", "token": "…", "url": "https://misi.link/aB3dE5fG",
"files": [{"id": 101, "name": "film.mov", "size": 5368709120}], "chunk_size": 8388608}2. Prześlij pliki
Wysyłaj każdy plik w częściach po maksymalnie „chunk_size” bajtów, po kolei: „offset” to liczba bajtów tego pliku już odebranych. Po przerwie „status” pokazuje, skąd wznowić (odpowiedź 409: wznów od „received”). Jeśli hosting lub zapora filtruje adresy, wyślij pozycję w nagłówku X-Upload-Offset zamiast w adresie.
curl -X POST "https://misi.link/api/upload/chunk?id=aB3dE5fG&token=…&file=101&offset=0" \
-H "Content-Type: application/octet-stream" --data-binary @morceau-1.bin
# {"ok": true, "received": 8388608, "done": false}
curl "https://misi.link/api/upload/status?id=aB3dE5fG&token=…"3. Zakończ
Gdy wszystkie pliki zostaną odebrane, zakończ: transfer trafia do sieci, a e-maile zostają wysłane. Link pochodzi z pierwszej odpowiedzi („url”). Ten krok jest obowiązkowy. Następnie serwer zapisuje pliki: w tym czasie „status” ma wartość „finalizing”. Transfer odebrany w całości, ale niezakończony, zostaje zakończony automatycznie po 30 minutach bez aktywności.
curl -X POST https://misi.link/api/upload/complete -H "Content-Type: application/json" \
-d '{"id": "aB3dE5fG", "token": "…"}'Wysyłanie bezpośrednio do magazynu (zalecane dla dużych plików)
Z „direct”: true Twój program wysyła plik bezpośrednio do magazynu misi.link, z pominięciem serwera: maksymalna prędkość i publikacja w kilka sekund na końcu. Jeden plik na transfer (kilka: połącz je w archiwum). Bez tej opcji lub gdy odpowiedź zawiera „direct”: null, wysyłaj części przez „chunk” jak wyżej.
- Utwórz transfer z „direct”: true. Odpowiedź podaje „direct.part_size” (rozmiar każdej części, ostatnia jest krótsza), „direct.parts” (liczbę części) i „direct.sign”.
- Pobierz podpisane adresy z „sign” (identyfikator, token i numery części, maks. 100 na wywołanie; ważne 6 godzin), a następnie wyślij każdą część zwykłym PUT na jej adres, bez nagłówka uwierzytelniania. Części można wysyłać równolegle i ponawiać po błędzie.
- Zakończ przez „complete”. Jeśli brakuje części, odpowiedź to „incomplete” z listą „missing”: wyślij te części ponownie i wywołaj „complete” jeszcze raz. Szyfrowanie end-to-end: każda część to ciąg pełnych zaszyfrowanych segmentów, po kolei (zob. przykład).
curl -X POST https://misi.link/api/v1/transfers -H "Authorization: Bearer $MISILINK_KEY" -H "Content-Type: application/json" \
-d '{"files": [{"name": "film.mov", "size": 5368709120}], "direct": true}'
# {…, "direct": {"part_size": 16777216, "parts": 320, "total": 5368709120, "sign": "https://misi.link/api/upload/sign"}}
curl -X POST https://misi.link/api/upload/sign -H "Content-Type: application/json" \
-d '{"id": "aB3dE5fG", "token": "…", "parts": [1, 2, 3]}'
# {"ok": true, "urls": {"1": "https://…", "2": "https://…", "3": "https://…"}}
curl -X PUT -H "Content-Type: application/octet-stream" --data-binary @part-1.bin "https://…"
curl -X POST https://misi.link/api/upload/complete -H "Content-Type: application/json" -d '{"id": "aB3dE5fG", "token": "…"}'
# {"ok": false, "error": "incomplete", "missing": [2]}Szyfrowanie end-to-end (opcjonalne)
Twój program szyfruje plik przed wysłaniem: misi.link odbiera i przechowuje tylko nieczytelne dane. Klucz nigdy nie trafia na serwer: jest w linku, po „#”. Odbiorca pobiera i odszyfrowuje w przeglądarce, na zwykłej stronie.
- Wylosuj klucz o długości 16 bajtów, a następnie utwórz transfer z „e2e”: true i jednym plikiem (jego rozmiar przed szyfrowaniem, w bajtach). Kilka plików połącz najpierw w archiwum.
- Klucz szyfrowania: HKDF-SHA-256 klucza (sól „misilink-e2e-v1”, info = identyfikator transferu, 16 bajtów), dla AES-GCM.
- Podziel plik na segmenty po 4 MiB (4 194 304 bajty). Segment nr i: nonce = 4 bajty zerowe, a potem i na 8 bajtach (big-endian); dane powiązane = i na 8 bajtach, a potem 1 bajt (1 dla ostatniego segmentu, w przeciwnym razie 0). Każdy zaszyfrowany segment jest dłuższy o 16 bajtów: wysyłaj te bajty przez „chunk”, po kolei („e2e.encrypted_size” łącznie), i zakończ przez „complete”.
- Zalecane: „e2e_verify” = HKDF-SHA-256 klucza (ta sama sól, info „misilink-verify”, 32 bajty) w base64url. misi.link odrzuci wtedy pobieranie ze złym kluczem, nigdy nie znając właściwego.
- Link do udostępnienia: „url” + „#” + klucz w base64url (22 znaki). Z odbiorcami („recipients”) dodaj „e2e_key” (klucz): misi.link przechowuje go zapieczętowany, by wstawić go do linków w e-mailach.
curl -X POST https://misi.link/api/v1/transfers \
-H "Authorization: Bearer $MISILINK_KEY" -H "Content-Type: application/json" \
-d '{"files": [{"name": "film.mov", "size": 5368709120}], "e2e": true, "e2e_verify": "…"}'
# {"ok": true, "id": "aB3dE5fG", …, "e2e": {"segment": 4194304, "tag": 16, "encrypted_size": 5368729600, "version": 1}}Pełny przykład w Pythonie (biblioteka cryptography):
#!/usr/bin/env python3
# misi.link: end-to-end encrypted upload through the API (Python 3.8+, pip install cryptography)
# The file goes straight to the storage (signed URLs); if direct upload is unavailable, through "chunk".
# Usage: MISILINK_KEY=mlk_... python3 misilink_e2e.py file.mov [https://misi.link]
import base64, json, os, sys, urllib.request
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from cryptography.hazmat.primitives.hashes import SHA256
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
SEG, SALT = 4 * 1024 * 1024, b'misilink-e2e-v1'
b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b'=').decode()
hkdf = lambda ikm, info, n: HKDF(SHA256(), n, SALT, info).derive(ikm)
def call(url, body=None, raw=None, headers=None, method=None, auth=True):
h = dict(headers or {})
if auth:
h['Authorization'] = 'Bearer ' + os.environ['MISILINK_KEY']
data = raw if raw is not None else (json.dumps(body).encode() if body is not None else None)
if data is not None:
h.setdefault('Content-Type', 'application/octet-stream' if raw is not None else 'application/json')
req = urllib.request.Request(url, data=data, headers=h, method=method or ('POST' if data is not None else 'GET'))
with urllib.request.urlopen(req, timeout=600) as r:
body = r.read()
return json.loads(body) if body[:1] == b'{' else {}
def segments(path, key, size):
n = max(1, -(-size // SEG))
with open(path, 'rb') as f:
for i in range(n):
last = i == n - 1
nonce = bytes(4) + i.to_bytes(8, 'big')
aad = i.to_bytes(8, 'big') + (b'\x01' if last else b'\x00')
yield key.encrypt(nonce, f.read(SEG), aad) # SEG bytes in, SEG + 16 bytes out
def send(path, base='https://misi.link'):
size = os.path.getsize(path)
secret = os.urandom(16) # the key: never sent to the server
verify = b64(hkdf(secret, b'misilink-verify', 32)) # lets the server recognise the right key
t = call(base + '/api/v1/transfers', {'files': [{'name': os.path.basename(path), 'size': size}],
'e2e': True, 'e2e_verify': verify, 'direct': True})
key = AESGCM(hkdf(secret, t['id'].encode(), 16))
auth = {'id': t['id'], 'token': t['token']}
d = t.get('direct')
if d: # straight to the storage: parts of d['part_size'] bytes
part, n, urls = b'', 0, {}
def put(n, data):
if str(n) not in urls:
urls.update(call(d['sign'], {**auth, 'parts': list(range(n, min(n + 100, d['parts'] + 1)))})['urls'])
call(urls[str(n)], raw=data, method='PUT', auth=False)
for seg in segments(path, key, size):
part += seg
if len(part) == d['part_size']:
n += 1; put(n, part); part = b''
if part:
n += 1; put(n, part)
else: # through the server
sent = 0
for seg in segments(path, key, size):
r = call(t['upload']['chunk'] + '?id=' + t['id'] + '&token=' + t['token'] + '&file=' + str(t['files'][0]['id']),
raw=seg, headers={'X-Upload-Offset': str(sent)})
sent = r['received']
call(t['upload']['complete'], auth)
return t['url'] + '#' + b64(secret) # the key travels after "#", only in the link
if __name__ == '__main__':
print(send(sys.argv[1], *(sys.argv[2:3] or [])))
Inne żądania
GET /api/v1/transfers- Twoje transfery, 50 na stronę (?page=2…).
GET /api/v1/transfers/{id}- Jeden transfer: stan, link, pliki, liczba pobrań, data wygaśnięcia.
DELETE /api/v1/transfers/{id}- Usuń transfer (link przestaje działać).
GET /api/v1/me- Twoje konto, twój plan i jego limity, rozmiar części.
Daty w formacie ISO 8601 (UTC), rozmiary w bajtach.
Odpowiedzi i błędy
Wszystkie odpowiedzi są w JSON, z „ok”. W razie błędu: „error” (krótki kod) i „message”. Kody HTTP: 401 brak klucza lub nieprawidłowy klucz, 403 plan bez API, 404 nie znaleziono, 409 część w złym miejscu, 422 żądanie odrzucone, 429 zbyt wiele żądań (odczekaj minutę).