krz/rune
an ios client for njalla
clone: git clone https://gitbay.org/krz/rune.git
v1.0.0: API.md · raw
1API Documentation
2-----------------
3
4API Endpoint: **https://njal.la/api/1/**
5Requests follow the JSON-RPC 2.0 protocol.
6You can use session cookies or token based authentication.
7POST JSON body to the API Endpoint:
8
9 {
10 "jsonrpc": "2.0",
11 "method": "...",
12 "params": {...},
13 "id": "123"
14 }
15
16and you will get a JSON response. Success:
17
18 {
19 "jsonrpc": "2.0",
20 "result": {}.
21 "id": "123"
22 }
23
24or error:
25
26 {
27 "jsonrpc": "2.0",
28 "error": {
29 "code": 0
30 "message": ""
31 },
32 "id": "123"
33 }
34
35Example using python requests
36
37 import requests
38
39 def njalla(method, **params):
40 url = 'https://njal.la/api/1/'
41 token = '<your-api-token>'
42 headers = {
43 'Authorization': 'Njalla ' + token
44 }
45 response = requests.post(url, json={
46 'method': method,
47 'params': params
48 }, headers=headers).json()
49 if 'result' not in response:
50 raise Exception('API Error', response)
51 return response['result']
52
53
54 print(njalla('list-domains'))
55 print(njalla('get-domain', domain='example.com'))
56
57
58Example using curl
59
60 NJALLA_TOKEN='<your-api-token>'
61 curl -s \
62 -H "Accept: application/json" \
63 -H "Content-Type: application/json" \
64 -H "Authorization: Njalla ${NJALLA_TOKEN}" \
65 --data '{"method":"get-domain", "params": {"domain": "exampe.com"}}' \
66 https://njal.la/api/1/
67
68
69api
70===
71
72add-token
73
74Add a new API token
75
76 params: {
77 comment: string (optional)
78 from: [string] (optional) array of IPv4 or IPv6 IPs or networks
79 that are allowed to use the token.
80 i.e.: ['8.8.8.8', '192.168.0.0/24']
81 allowed_domains: [string] (optional) restrict token to subset of your domains
82 allowed_servers: [string] (optional) restrict token to subset of your servers by id
83 allowed_methods: [string] (optional) restrict token to subset of possible API calls
84 allowed_prefixes: [string] (optional) restrict token to DNS record name prefixes
85 allowed_types: [string] (optional) restrict token to subset of possible types of DNS records
86 acme: bool (optional) syntax sugar adding allowed_methods,
87 allowed_prefixes and allowed_types
88 needed for ACME DNS challenge
89 }
90 returns: {
91 }
92
93check-task
94
95Check status of a long running task
96
97 params: {
98 id: string
99 }
100 returns: {
101 id: string
102 status: object
103 }
104
105edit-token
106
107Edit API token
108
109 params: {
110 key: string
111 comment: string (optional)
112 from: [string] (optional) array of IPv4 or IPv6 IPs or networks
113 that are allowed to use the token.
114 i.e.: ['8.8.8.8', '192.168.0.0/24']
115 allowed_domains: [string] (optional) restrict token to subset of your domains
116 allowed_servers: [string] (optional) restrict token to subset of your servers by id
117 allowed_methods: [string] (optional) restrict token to subset of possible API calls
118 allowed_prefixes: [string] (optional) restrict token to DNS record name prefixes
119 allowed_types: [string] (optional) restrict token to subset of possible types of DNS records
120 }
121 returns: {
122 }
123
124list-tokens
125
126List existing API authorization tokens.
127
128 params: {
129 }
130 returns: {
131 tokens: [...]
132 }
133
134remove-token
135
136Remove an existing API token
137
138 params: {
139 key: string
140 }
141 returns: {
142 }
143
144domain
145======
146
147add-dnssec
148
149Add DNSSEC record for domain
150
151 params: {
152 domain: string
153 algorithm: integer
154
155 digest: string
156 digest_type: integer
157 key_tag: integer
158
159 or
160
161 public_key: string
162 }
163 returns: {
164 }
165
166add-forward
167
168Add email forward
169
170 params: {
171 domain: string
172 from: string
173 to: string
174 }
175 returns: {
176 domain: string
177 from: string
178 to: string
179 }
180
181add-glue
182
183Add glue record for the domain, name is the subdomain
184
185 params: {
186 domain: string
187 name: string
188 address4: string
189 address6: string
190 }
191 returns: {
192 }
193
194add-record
195
196Add new DNS Record to domain
197
198 params: {
199 domain: string
200 type: string (types: A, AAAA, ANAME, CAA, CNAME, DS, Dynamic, HTTPS, MX, NAPTR, NS, PTR, SRV, SSHFP, SVCB, TLSA, TXT)
201 name: string (all types)
202 content: string (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, Static, TLSA, TXT)
203 ttl: int (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, TLSA, TXT)
204 prio: int (types: HTTPS, MX, Redirect, SRV, SVCB)
205 weight: int (types: SRV)
206 port: int (types: SRV)
207 target: string (types: HTTPS, SVCB)
208 ssh_algorithm: int (types: SSHFP, values: 1-5 // RSA, DSA, ECDSA, Ed25519, XMSS)
209 ssh_type: int (types: SSHFP, values: 1-2 // SHA-1, SHA-256)
210 }
211 returns: {
212 id: string
213 domain: string
214 type: string (types: A, AAAA, ANAME, CAA, CNAME, DS, Dynamic, HTTPS, MX, NAPTR, NS, PTR, SRV, SSHFP, SVCB, TLSA, TXT)
215 name: string (all types)
216 content: string (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, Static, TLSA, TXT)
217 ttl: int (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, TLSA, TXT)
218 prio: int (types: HTTPS, MX, Redirect, SRV, SVCB)
219 weight: int (types: SRV)
220 port: int (types: SRV)
221 target: string (types: HTTPS, SVCB)
222 ssh_algorithm: int (types: SSHFP, values: 1-5 // RSA, DSA, ECDSA, Ed25519, XMSS)
223 ssh_type: int (types: SSHFP, values: 1-2 // SHA-1, SHA-256)
224 }
225
226edit-domain
227
228Edit domain configuration
229
230 params: {
231 domain: string
232 ...
233 }
234 possible keys:
235 mailforwarding: boolean
236 dnssec: boolean
237 lock: boolean
238 contacts: custom whois contact ids
239 nameservers: list of custom nameservers or empty list to use our nameservers
240
241 returns: {
242 name: string,
243 ...
244 }
245
246edit-glue
247
248Edit glue record
249
250 params: {
251 domain: string
252 name: string
253 address4: string
254 address6: string
255 }
256 returns: {
257 }
258
259edit-record
260
261Edit DNS Record
262
263 params: {
264 id: string
265 domain: string
266 type: string (types: A, AAAA, ANAME, CAA, CNAME, DS, Dynamic, HTTPS, MX, NAPTR, NS, PTR, SRV, SSHFP, SVCB, TLSA, TXT)
267 name: string (all types)
268 content: string (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, Static, TLSA, TXT)
269 ttl: int (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, TLSA, TXT)
270 prio: int (types: HTTPS, MX, Redirect, SRV, SVCB)
271 weight: int (types: SRV)
272 port: int (types: SRV)
273 target: string (types: HTTPS, SVCB)
274 ssh_algorithm: int (types: SSHFP, values: 1-5 // RSA, DSA, ECDSA, Ed25519, XMSS)
275 ssh_type: int (types: SSHFP, values: 1-2 // SHA-1, SHA-256)
276 }
277 returns: {
278 domain: string
279 type: string (types: A, AAAA, ANAME, CAA, CNAME, DS, Dynamic, HTTPS, MX, NAPTR, NS, PTR, SRV, SSHFP, SVCB, TLSA, TXT)
280 name: string (all types)
281 content: string (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, Static, TLSA, TXT)
282 ttl: int (types: A, AAAA, ANAME, CAA, CNAME, DS, MX, NAPTR, NS, PTR, Redirect, SRV, SSHFP, TLSA, TXT)
283 prio: int (types: HTTPS, MX, Redirect, SRV, SVCB)
284 weight: int (types: SRV)
285 port: int (types: SRV)
286 target: string (types: HTTPS, SVCB)
287 ssh_algorithm: int (types: SSHFP, values: 1-5 // RSA, DSA, ECDSA, Ed25519, XMSS)
288 ssh_type: int (types: SSHFP, values: 1-2 // SHA-1, SHA-256)
289 }
290
291find-domains
292
293Find new domains
294
295 params: {
296 query: string
297 }
298 returns: {
299 domains: [
300 {price: int, status: string, name: string}
301 ]
302 }
303
304get-domain
305
306Get information about one of your domains
307
308 params: {
309 domain: string
310 }
311 returns: {
312 name: string,
313 ...
314 }
315
316get-tlds
317
318Get list of supported TLDs
319
320 params: {
321 }
322 returns: {
323 tld: {price: int, max_year: int, dnssec: boolean},
324 }
325
326import-zone
327
328Import BIND zone file
329
330 params: {
331 domain: string
332 zone: string
333 }
334 returns: {
335 }
336
337list-dnssec
338
339List DNSSEC records for domain
340
341 params: {
342 domain: string
343 }
344 returns: {
345 dnssec: list
346 }
347
348list-domains
349
350Get list of your domains
351
352 params: {
353 }
354 returns: {
355 domains: list
356 }
357
358list-forwards
359
360List existing email forwards
361
362 params: {
363 domain: string
364 }
365 returns: {
366 forwards: list
367 }
368
369list-glue
370
371List glue records for domain
372
373 params: {
374 domain: string
375 }
376 returns: {
377 glue: list
378 }
379
380list-records
381
382List DNS records for given domain
383
384 params: {
385 domain: string
386 }
387 returns: {
388 records: list
389 }
390
391register-domain
392
393Register a new domain
394
395 params: {
396 domain: string
397 years: int (default: 1)
398 }
399 returns: {
400 task: string
401 }
402 use check-task for response
403
404remove-dnssec
405
406Remove DNSSEC record from domain
407
408 params: {
409 domain: string
410 id: string
411 }
412 returns: {
413 }
414
415remove-forward
416
417Remove email forward
418
419 params: {
420 domain: string
421 from: string
422 to: string
423 }
424 returns: {
425 }
426
427remove-glue
428
429Remove glue record
430
431 params: {
432 domain: string
433 name: string
434 }
435 returns: {
436 }
437
438remove-record
439
440Remove DNS Record
441
442 params: {
443 domain: string
444 id: string
445 name: string // optional
446 type: string // optional
447 ... // optional
448 }
449
450 remove a dns record by id
451 or multiple records by passing name, type and any other existing record's field
452
453 returns: {
454 records: list
455 }
456
457renew-domain
458
459Renew one of your domains
460
461 params: {
462 domain: string
463 years: int (default: 1)
464 }
465 returns: {
466 task: string
467 }
468 use check-task for response
469
470server
471======
472
473add-server
474
475Create a new server with the given name, type, os and ssh\_key. Returns an id of the newly created server
476
477 params: {
478 name: string,
479 type: string
480 os: string
481 ssh_key: string
482 months: int (max 12)
483 autorenew: bool
484 }
485 returns: {
486 id: string
487 ...
488 }
489
490add-traffic
491
492Add extra traffic package.
493
494 params: {
495 id: string
496 amount: int
497 months: int
498 starts_today: bool
499 }
500 returns: {
501 ...
502 }
503
504edit-server
505
506Edit an existing server identified by id
507
508 params: {
509 id: string
510 name: string,
511 type: string
512 ssh_key: string
513 reverse_name: string
514 autorenew: bool
515 }
516 returns: {
517 ...
518 }
519
520get-server
521
522Returns information about one of your servers
523
524 params: {
525 id: string
526 }
527 returns: {
528 ...
529 }
530
531list-server-images
532
533Returns a list of server images that can be used for new servers
534
535 params: {
536 }
537 returns: {
538 images: list
539 }
540
541list-server-types
542
543Returns a list of server types that can be used for new servers
544
545 params: {
546 }
547 returns: {
548 types: list
549 }
550
551list-servers
552
553Returns a list of your servers
554
555 params: {
556 }
557 returns: {
558 servers: list
559 }
560
561list-traffic
562
563List extra traffic packages per server.
564
565 params: {
566 id: string # server id
567 }
568 returns: {
569 traffic: []
570 }
571
572remove-server
573
574Remote an existing server, your server will be stopped and all data deleted.
575
576 params: {
577 id: string
578 }
579 returns: {
580 task: string
581 }
582
583renew-server
584
585Renew an existing server identified by id, your wallet must have enough credit to complete this operation.
586
587 params: {
588 id: string
589 months: int
590 }
591 returns: {
592 ...
593 }
594
595reset-server
596
597Reset existing server and reinstall the given os. All data will be lost. Required field: \`id\`
598
599 params: {
600 id: string
601 os: string
602 ssh_key: string
603 type: string
604 }
605 returns: {
606 ...
607 }
608
609restart-server
610
611Restart existing server
612
613 params: {
614 id: string
615 }
616 returns: {
617 ...
618 }
619
620start-server
621
622Start existing server
623
624 params: {
625 id: string
626 }
627 returns: {
628 ...
629 }
630
631stop-server
632
633Stop existing server
634
635 params: {
636 id: string
637 }
638 returns: {
639 ...
640 }
641
642user
643====
644
645delete-account
646
647Delete your account. You can only delete the account if all domains and servers have been removed and your wallet is empty.
648
649 params: {
650 }
651 returns: {
652 }
653
654login
655
656Login into an existing account (cookie based session). Consider using API tokens instead
657
658 params: {
659 email: string [or] xmpp: string
660 password: string
661 }
662 returns: {
663 }
664
665logout
666
667Logout and end your current session
668
669 params: {
670 }
671 returns: {
672 }
673
674vpn
675===
676
677add-vpn
678
679Add a new VPN client Returns an id
680
681 params: {
682 name: string,
683 autorenew: boolean
684 }
685 returns: {
686 id: string
687 ...
688 }
689
690edit-vpn
691
692Edit an existing VPN identified by id
693
694 params: {
695 id: string
696 name: string,
697 autorenew: boolean
698 backend: wireguard|openvpn
699 publickey: WireGuard PublicKey, set to your public key or null to generate a new one
700 }
701 returns: {
702 ...
703 }
704
705get-vpn
706
707Returns information about VPN
708
709 params: {
710 id: string
711 }
712 returns: {
713 ...
714 }
715
716list-vpns
717
718Returns a list of your VPNs
719
720 params: {
721 }
722 returns: {
723 vpns: list
724 }
725
726remove-vpn
727
728Remove an existing VPN
729
730 params: {
731 id: string
732 }
733 returns: {
734 ...
735 }
736
737renew-vpn
738
739Renew an existing VPN identified by id, your wallet must have enough credit to complete this operation.
740
741 params: {
742 id: string
743 months: int
744 }
745 returns: {
746 ...
747 }
748
749wallet
750======
751
752add-payment
753
754Refill your wallet
755
756 params: {
757 amount: int (5 or multiple of 15, max: 300)
758 via: string (options: paypal, bitcoin, litecoin, monero, zcash, ethereum)
759 }
760 returns: {
761 amount: int
762 address: string (payment address)
763 url: string (paypal url to process payment)
764 }
765
766get-balance
767
768 params: {
769 }
770 returns: {
771 balance: int (in euros)
772 }
773
774get-payment
775
776Get details about a payment
777
778 params: {
779 id: string
780 }
781 returns: {
782 id: string
783 amount: int
784 status: string
785 address: string
786 url: string
787 }
788
789list-transactions
790
791List transactions (payments, registrations, renewals, etc..) of the last 90 days
792
793 params: {
794 }
795 returns: {
796 transactions: list
797 }