This document provides documention of the API to control JS8Call.

Methods

The API is normally located on localhost port 2242, but can be changed at Settings -> Reporting Tab -> API If you have access to telnet you can connect to the API with

telnet 127.0.0.1 2242

If you do nothing, the API will print information as it has it available, or you can submit one of the End Points below.

API Format

All API calls are via JSON. JS8Call spits out a JSON packet of the form (for a heartbeat in this case):

{"params":{"PTT":true,"UTC":1768760160665,"_ID":-1},"type":"RIG.PTT","value":"on"}
{"params":{"TONES":[4,2,5,6,1,3,0,7,1,5,7,6,0,2,2,3,7,4,2,7,6,4,5,1,7,1,7,3,6,6,4,1,0,4,1,7,4,2,5,6,1,3,0,0,2,4,2,1,1,4,1,6,3,4,4,4,6,2,0,7,0,5,6,2,3,1,0,3,7,4,6,4,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"TONES":[4,2,5,6,1,3,0,7,1,5,7,6,0,2,2,3,7,4,2,7,6,4,5,1,7,1,7,3,6,6,4,1,0,4,1,7,4,2,5,6,1,3,0,0,2,4,2,1,1,4,1,6,3,4,4,4,6,2,0,7,0,5,6,2,3,1,0,3,7,4,6,4,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"PTT":false,"UTC":1768760173403,"_ID":-1},"type":"RIG.PTT","value":"off"}

The steps above are 1) PTT on 2) Send HB MSG as TONES (2 transmission frames) 3) PTT off

{"params":xxx} is required in both directions and forms the overall packet

Commands	Version
PING	2.5
RIG.GET_FREQ	2.5
RIG.SET_FREQ	2.5
RIG.GET_PTT	2.6
RIG.SET_TUNE	2.6
RIG.TX_HALT	2.6
STATION.GET_CALLSIGN	2.5
STATION.GET_GRID	2.5
STATION.SET_GRID	2.5
STATION.GET_INFO	2.5
STATION.SET_INFO	2.5
STATION.GET_STATUS	2.5
STATION.SET_STATUS	2.5
STATION.VERSION	2.6
STATION.GET_OS	2.6
STATION.SET_STATUS	2.5
STATION.GET_SPOT	2.6
STATION.SET_SPOT	2.6
RX.GET_CALL_ACTIVITY	2.5
RX.GET_CALL_SELECTED	2.5
RX.GET_BAND_ACTIVITY	2.5
RX.GET_TEXT	2.5
RX.GET_FREE_OFFSETS	2.6
TX.GET_TEXT	2.5
TX.SET_TEXT	2.5
TX.SEND_MESSAGE	2.5
TX.GET_QUEUE_DEPTH	2.6
MODE.GET_SPEED	2.5
MODE.SET_SPEED	2.5
INBOX.GET_MESSAGES	2.5
INBOX.STORE_MESSAGE	2.5
WINDOW.RAISE	2.5

_ID Number

The ID number is the epoch time of 1499299200000 (July 6, 2017) plus current epoch time.

Error messages

Response
{"params":{"_ID":"269558031750"},"type":"API.ERROR","value":"unterminated object: json parsing error"}

value contains the error

STATION Message

[!note] API >= 2.6

The following message is generated by JS8Call when it is closing down.

Response
{"params":{"REASON":"User closed application","_ID":-1},"type":"STATION.CLOSING","value":""}

RX Messages

The following messages are generated by JS8Call and emitted out from the API as they come in.

RX.ACTIVITY

Response
{"params":{"DIAL":7078000,"FREQ":7080420,"OFFSET":2420,"SNR":-22,"SPEED":1,"TDRIFT":0.26499998569488525,"UTC":1769740328005,"_ID":-1},"type":"RX.ACTIVITY","value":"HC5PH: "}
{"params":{"CMD":" MSG","DIAL":7078000,"EXTRA":"","FREQ":7080420,"FROM":"HC5PH","GRID":" FI06","OFFSET":2420,"SNR":-24,"SPEED":1,"TDRIFT":0.23999999463558197,"TEXT":"F!104 2EE ST[EC] GR[FI06JS] #AUVO","TO":"@SITREP","UTC":1769740328005,"_ID":-1},"type":"RX.DIRECTED","value":"HC5PH: @SITREP MSG F!104 2EE ST[EC] GR[FI06JS] #AUVO ♢ "}

RX.DIRECTED

Response
{"params":{"CMD":" HEARTBEAT","DIAL":7078000,"EXTRA":"","FREQ":7078816,"FROM":"KE2DMC","GRID":"FN32","OFFSET":816,"SNR":1,"SPEED":0,"TDRIFT":0.5399999618530273,"TEXT":"","TO":"@HB","UTC":1769740226361,"_ID":-1},"type":"RX.DIRECTED","value":"KE2DMC: @HB HEARTBEAT ♢ "}

RX.SPOT

Response
{"params":{"CALL":"KF7MIX","DIAL":7078000,"FREQ":7078870,"GRID":"EM48","OFFSET":870,"SNR":-5,"_ID":-1},"type":"RX.SPOT","value":""}

PING

API <= 2.6

Wakes up the API if need be.

End Point
{"params":{},"type":"PING","value":""}

Requirements
value	empty string

Response
None

RIG.GET_FREQ

API <= 2.6

Gets radio dial and offset frequencies

End Point
{"params":{},"type":"RIG.GET_FREQ","value":""}

Requirements
value	empty string

Response
{"params":{"DIAL":7078000,"FREQ":7079950,"OFFSET":1950,"_ID":269554125481},"type":"RIG.FREQ","value":""}

FREQ is the DIAL frequency plus OFFSET

RIG.SET_FREQ

API <= 2.6

Sets radio dial and offset frequencies

End Point
{"params":{"DIAL":dial,"OFFSET":offset},"type":"RIG.SET_FREQ","value":""}

Requirements
dial	Frequency in Hz
offset	Offset in Hz
value	empty string

Response
{"params":{"DIAL":7078000,"FREQ":7079950,"OFFSET":1950,"SELECTED":"","SPEED":0,"_ID":"269554221645"},"type":"STATION.STATUS","value":""}

FREQ is the DIAL frequency plus OFFSET SPEED is one of the MODE speeds

RIG.GET_PTT

[!note] API >= 2.6

Gets rig PTT status

End Point
{"params":{},"type":"RIG.GET_PTT","value":""}

Requirements
value	empty string

Response
{"params":{"MESSAGE":"","PTT":false,"_ID":269908447335},"type":"RIG.PTT_STATUS","value":""}
{"params":{"MESSAGE":"SLbuEVAt7YC0","PTT":true,"_ID":269908640060},"type":"RIG.PTT_STATUS","value":""}

MESSAGE will be empty string or a message if more is being transmitted.

PTT will be true if transmitting.

RIG.SET_TUNE

[!note] API >= 2.6

Sets TUNE setting on or off

End Point
{"params":{},"type":"RIG.SET_TUNE","value":"false"}

Requirements
value	true/false

Response
{"params":{"_ID":270422213693,"value":true},"type":"RIG.SET_TUNE","value":""}
{"params":{"PTT":true,"UTC":1769721024401,"_ID":-1},"type":"RIG.PTT","value":"on"}

{"params":{"_ID":270421833952,"value":false},"type":"RIG.SET_TUNE","value":""}
{"params":{"PTT":false,"UTC":1769721034501,"_ID":-1},"type":"RIG.PTT","value":"off"}

NOTE: Both the SET_TUNE and PTT response messages are triggered. As there is a built-in max time on the tuning, no GET call exists.

RIG.TX_HALT

[!note] API >= 2.6

Halts the transmitter immediately

End Point
{"params":{},"type":"RIG.TX_HALT","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":270426906894,"value":true},"type":"RIG.TX_HALT","value":""}

STATION.GET_CALLSIGN

API <= 2.6

Gets station callsign

End Point
{"params":{},"type":"STATION.GET_CALLSIGN","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":269553944755},"type":"STATION.CALLSIGN","value":"callsign"}

Callsign is returned in value

STATION.GET_GRID

API <= 2.6

Gets station grid square

End Point
{"params":{},"type":"STATION.GET_GRID","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":269558175403},"type":"STATION.GRID","value":"EM85"}

Grid square is returned in value

STATION.SET_GRID

API <= 2.6

Sets station grid square

End Point
{"params":{},"type":"STATION.SET_GRID","value":grid}

Requirements
grid	4 or 6 character grid square enclosed in ""

Response
{"params":{"_ID":269558371794},"type":"STATION.GRID","value":"EM85"}

Grid square is returned in value

STATION.GET_INFO

API <= 2.6

Gets station info

End Point
{"params":{},"type":"STATION.GET_INFO","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":269559398161},"type":"STATION.INFO","value":"JS8-IMPROVED VER <MYVERSION>"}

Station info is returned in value

STATION.SET_INFO

API <= 2.6

Sets station info

End Point
{"params":{},"type":"STATION.SET_INFO","value":info}

Requirements
value	Station info enclosed in ""

Response
{"params":{"_ID":269559620289},"type":"STATION.INFO","value":"JS8-IMPROVED VER <MYVERSION>"}

Station info is returned in value

STATION.GET_STATUS

API <= 2.6

Gets station status message

End Point
{"params":{},"type":"STATION.GET_STATUS","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":269559773383},"type":"STATION.STATUS","value":"IDLE <MYIDLE> JS8CALL-IMPORVED VERSION <MYVERSION>"}

Station status is returned in value

STATION.SET_STATUS

API <= 2.6

Sets station status message

End Point
{"params":{},"type":"STATION.SET_STATUS","value":""}

Requirements
value	Station status enclosed in ""

Response
{"params":{"_ID":269559773383},"type":"STATION.STATUS","value":"IDLE <MYIDLE> JS8CALL-IMPORVED VERSION <MYVERSION>"}

Station status is returned in value

STATION.VERSION

[!note] API >= 2.6

Gets JS8Call version. Use to check for API changes or compatiblity.

End Point
{"params":{},"type":"STATION.VERSION","value":""}

Requirements
value	empty string

Response
{"params":{"VERSION":"2.6.0-NOT_FOR_RELEASE","_ID":269908381596},"type":"STATION.VERSION","value":""}

STATION.GET_OS

[!note] API >= 2.6

Gets OS info including name, kernel version, and type

End Point
{"params":{},"type":"STATION.GET_OS","value":""}

Requirements
value	empty string

Response
{"params":{"OS_KERNEL":"linux","OS_KERNEL_VERSION":"6.14.0-37-generic","OS_NAME":"Ubuntu 24.04.3 LTS","_ID":269977840701},"type":"STATION.GET_OS","value":""}

STATION.GET_SPOT

[!note] API >= 2.6

Gets status of SPOT setting

End Point
{"params":{},"type":"STATION.GET_SPOT","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":270409823907,"value":true},"type":"STATION.SPOT","value":""}

STATION.SET_SPOT

[!note] API >= 2.6

Sets status of SPOT setting

End Point
{"params":{},"type":"STATION.SET_SPOT","value":"true"}

Requirements
value	true/false

Response
{"params":{"_ID":270409737648,"value":true},"type":"STATION.SPOT","value":""}

RX.GET_CALL_ACTIVITY

API <= 2.6

Returns the recent call activity

End Point
{"params":{},"type":"RX.GET_CALL_ACTIVITY","value":""}

Requirements
value	empty string

Response
{"params":{"":{"GRID":"","SNR":0,"UTC":0},"AB4WV":{"GRID":"","SNR":-18,"UTC":1768858992167},"K4EXA":{"GRID":"EM63","SNR":-18,"UTC":1768858242147},"type":"RX.CALL_ACTIVITY","value":""}

RX.GET_CALL_SELECTED

API <= 2.6

Returns the callsign of a station that has been selected in the UI.

End Point
{"params":{},"type":"RX.GET_CALL_SELECTED","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":269560590229},"type":"RX.CALL_SELECTED","value":""}
{"params":{"_ID":269560649847},"type":"RX.CALL_SELECTED","value":"KM4PVB"}

1) First form is if no callsign is currently selected in the UI.

2) Second form is the selected callsign in the UI.

RX.GET_BAND_ACTIVITY

API <= 2.6

Gets current band activity

End Point
{"params":{},"type":"RX.GET_BAND_ACTIVITY","value":""}

Requirements
value	empty string

Response
{"params":{"1067":{"DIAL":7078000,"FREQ":7079067,"OFFSET":1067,"SNR":-7,"TEXT":"W6OEM: VE3SOY HEARTBEAT SNR -20 ","UTC":1768860611907},"616":{"DIAL":7078000,"FREQ":7078616,"OFFSET":616,"SNR":-18,"TEXT":"KM4BOF: VE3SOY HEARTBEAT SNR -09 ","UTC":1768860611918},"type":"RX.BAND_ACTIVITY","value":""}

RX.GET_TEXT

API <= 2.6

Gets the contents of the directed message window

End Point
{"params":{},"type":"RX.GET_TEXT","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":269562514193},"type":"RX.TEXT","value":"\n22:06:10 - (1950) - KJ4CTD: W4CAT SNR? ♢ \n\n22:06:52 - (1950) - KJ4CTD: KB4DSF SNR? ♢ \n\n22:14:29 - (800) - KJ4CTD: N0AAS HEARTBEAT SNR -18 ♢ \n\n22:25:31 - (1950) - KJ4CTD: @SITREP MSG F!104 100 ST[SC] GR[EM85] #ASRM KWC ♢ "}

RX.GET_FREE_OFFSETS

[!note] API >= 2.6

Returns contiguous free offset segments in the passband not occupied by recently heard stations. Accounts for the bandwidth of each active signal's submode so the returned segments are guaranteed wide enough for your intended transmission without overlapping other stations.

Entries older than 30 seconds are considered stale and treated as clear.

End Point
{"params":{},"type":"RX.GET_FREE_OFFSETS","value":""}
{"params":{"SPEED":2,"LOW":500,"HIGH":2500},"type":"RX.GET_FREE_OFFSETS","value":""}

Optional params
SPEED	Submode int (0=Normal, 1=Fast, 2=Turbo, 4=Slow, 8=Ultra). Defaults to current mode.
LOW	Low passband bound in Hz. Default: 500
HIGH	High passband bound in Hz. Default: 2500

Response
{"params":{"FREE":[{"HIGH":860,"LOW":500,"WIDTH":360},{"HIGH":2500,"LOW":1120,"WIDTH":1380}],"BANDWIDTH":160,"HIGH":2500,"LOW":500,"SPEED":2,"_ID":269562514193},"type":"RX.FREE_OFFSETS","value":""}

FREE is a list of free segments, each with LOW, HIGH, and WIDTH in Hz. BANDWIDTH is the signal bandwidth (Hz) for the requested SPEED. Segments narrower than BANDWIDTH are omitted — they cannot fit the intended transmission.

TX.GET_TEXT

API <= 2.6

Gets the text to be transmitted

End Point
{"params":{},"type":"TX.GET_TEXT","value":""}

Requirements
value	empty string

Response
{"params":{"_ID":269562593590},"type":"TX.TEXT","value":""}
{"params":{"_ID":269562644567},"type":"TX.TEXT","value":"KJ4CTD: KJ4YQK SOME RANDOM TEXT"}

1) If text box is empty 2) If text box has something in it

TX.SET_TEXT

API <= 2.6

Sets the text to be transmitted

End Point
{"params":{},"type":"TX.SET_TEXT","value":""}

Requirements
value	text to be transmitted

Response
{"params":{"_ID":269563119535},"type":"TX.TEXT","value":"TEST"}

TX.SEND_MESSAGE

API <= 2.6

Sends the value in the next transmit cycle

[NOTE] If the message window already has text displayed, this will NOT transmit your new message!

End Point
{"params":{},"type":"TX.SEND_MESSAGE","value":""}

Requirements
value	text to be transmitted

Response
{"params":{"PTT":true,"UTC":1768862879801,"_ID":-1},"type":"RIG.PTT","value":"on"}
{"params":{"TONES":[4,2,5,6,1,3,0,1,0,2,6,6,3,1,6,6,4,0,1,7,0,7,2,6,2,6,0,4,3,4,5,2,3,5,2,0,4,2,5,6,1,3,0,3,4,2,5,4,5,7,0,1,6,3,6,7,0,2,3,5,6,4,5,7,4,0,0,1,7,3,6,4,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"PTT":false,"UTC":1768862893402,"_ID":-1},"type":"RIG.PTT","value":"off"}
{"params":{"PTT":true,"UTC":1768862894801,"_ID":-1},"type":"RIG.PTT","value":"on"}
{"params":{"TONES":[4,2,5,6,1,3,0,2,3,7,1,3,7,7,5,2,2,4,1,1,2,2,1,1,5,3,5,4,0,7,0,5,2,1,6,5,4,2,5,6,1,3,0,7,1,6,4,4,3,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,2,6,7,1,2,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"PTT":false,"UTC":1768862908402,"_ID":-1},"type":"RIG.PTT","value":"off"}

1) Trigger PTT on 2) Send the message tones 3) Trigger PTT off 4) Trigger PTT on 5) Send the message tones 6) Trigger PTT off

TX.GET_QUEUE_DEPTH

[!note] API >= 2.6

Gets the number of messages left in the transmit queue.

End Point
{"params":{},"type":"TX.GET_QUEUE_DEPTH","value":""}

Requirements
value	empty string

Response
{"params":{"DEPTH":2,"_ID":270440267253},"type":"TX.QUEUE_DEPTH","value":""}

MODE.GET_SPEED

API <= 2.6

Gets the currently set transmit mode speed

End Point
{"params":{},"type":"MODE.GET_SPEED","value":""}

Requirements
value	empty string

Response
{"params":{"SPEED":0,"_ID":269564224294},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":1,"_ID":269564372867},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":2,"_ID":269564383363},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":4,"_ID":269564510080},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":8,"_ID":269564511182},"type":"MODE.SPEED","value":""}

MODE.SET_SPEED

API <= 2.6

Sets the currently set transmit mode speed

End Point
{"params":{"SPEED":speed},"type":"MODE.SET_SPEED","value":""}

Requirements
speed	mode speed number
value	empty string

Response
{"params":{"DIAL":7078000,"FREQ":7079950,"OFFSET":1950,"SELECTED":"","SPEED":0,"_ID":"269564663038"},"type":"STATION.STATUS","value":""}
{"params":{"SPEED":0,"_ID":270412242558},"type":"MODE.SET_SPEED","value":""}

Sometimes it comes back with the first form.

MODE Speeds

Mode	Number
Normal	0
Fast	1
JS8 40	2
Slow	4
JS8 60	8

Please note, JS8 60 is an experimental and unreliable mode.

INBOX.GET_MESSAGES

API <= 2.6

Fetches all Inbox messages, warning, this could be very large

End Point
{"params":{},"type":"INBOX.GET_MESSAGES","value":""}

Requirements
value	empty string

Response
{"params":{"MESSAGES":[{"params":{"CMD":" MSG ","DIAL":7078000,"FREQ":7080318,"FROM":"KJ5MIW","GRID":" EM15","OFFSET":2318,"PATH":"KJ5MIW","SNR":-15,"SUBMODE":0,"TDRIFT":0.13999998569488525,"TEXT":"F!104 100 ST[OK] GR[EM15] #ATTV","TO":"@SITREP","UTC":"2026-01-21 01:44:26","_ID":"269660742003"},"type":"READ","value":""}],"_ID":269699597005},"type":"INBOX.MESSAGES","value":""}

MESSAGES is a comma seperated list of message records, each record is contained within brackets.

INBOX.STORE_MESSAGE

API <= 2.6

Stores a message in YOUR Inbox

End Point
{"params":{"CALLSIGN":callsign,"TEXT":text},"type":"INBOX.STORE_MESSAGE","value":""}}

Requirements
callsign	"TO" callsign in ""
text	Text to store in ""
value	empty string

Response
{"params":{"ID":228,"_ID":269569847892},"type":"INBOX.MESSAGE","value":""}

WINDOW.RAISE

API <= 2.6

If allowed by OS. brings the program to the front

End Point
{"params":{},"type":"WINDOW.RAISE","value":""}

Requirements
value	empty string

Response
None