Hamlib API

Getting Started

v4.5.0

The Hamlib API provides a RESTful interface for controlling amateur radio equipment and antenna rotators. This documentation covers all available endpoints, authentication methods, and includes an interactive playground for testing.

01

Install Hamlib

Install the Hamlib library and ensure rigctld or rotctld is running on your system.

02

Get API Key

Generate an API key from your Hamlib dashboard to authenticate your requests.

03

Make Requests

Start making API calls to control your radio or rotator using the endpoints below.

Base URL

Base URL
1http://localhost:4532/api

Quick Example

Quick Start
1curl -X GET "http://localhost:4532/api/radio/frequency" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json"

Authentication

Secure your API requests

The Hamlib API supports two authentication methods. All authenticated requests must include the appropriate credentials in the request headers.

API Key Authentication

Include your API key in the X-API-Key header. This is the recommended method for server-to-server communication.

API Key Header
1curl -H "X-API-Key: ham_k1abc2def3" \
2  http://localhost:4532/api/radio/frequency

Bearer Token

Use a Bearer token in the Authorization header. Ideal for applications using OAuth2 or JWT-based authentication flows.

Bearer Token
1curl -H "Authorization: Bearer eyJhbGc..." \
2  http://localhost:4532/api/radio/frequency

Rate Limiting

API requests are rate-limited to 100 requests per minute per API key. Rate limit headers are included in every response:X-RateLimit-RemainingandX-RateLimit-Reset.

API Reference

Complete reference for all available Hamlib API endpoints.

GET
/api/radio/frequency

Retrieve the current operating frequency of the radio. Returns the frequency in Hz along with the active VFO and a human-readable formatted string.

Parameters

NameTypeRequiredDescription
vfostringOptionalTarget VFO (e.g., VFOA, VFOB, currVFO). Defaults to currVFO.
cURL
1curl -X GET "http://localhost:4532/api/radio/frequency?vfo=currVFO" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json"
POST
/api/radio/frequency

Set the operating frequency of the radio. Accepts frequency in Hz and optionally specifies which VFO to tune.

Parameters

NameTypeRequiredDescription
frequencyintegerRequiredTarget frequency in Hz (e.g., 14250000 for 14.250 MHz).
vfostringOptionalTarget VFO (e.g., VFOA, VFOB). Defaults to currVFO.
cURL
1curl -X POST "http://localhost:4532/api/radio/frequency" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "frequency": 14250000,
6    "vfo": "VFOA"
7  }'
GET
/api/radio/mode

Get the current operating mode and passband width of the radio. Returns mode identifier (e.g., USB, LSB, CW, FM) and the passband width in Hz.

Parameters

NameTypeRequiredDescription
vfostringOptionalTarget VFO. Defaults to currVFO.
cURL
1curl -X GET "http://localhost:4532/api/radio/mode?vfo=currVFO" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json"
GET
/api/radio/vfo

Get the currently active VFO (Variable Frequency Oscillator). Returns which VFO is currently selected for receive and transmit operations.

cURL
1curl -X GET "http://localhost:4532/api/radio/vfo" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json"
POST
/api/radio/vfo

Set the active VFO. Switch between VFOs for receive and transmit operations. Supports standard VFO identifiers.

Parameters

NameTypeRequiredDescription
vfostringRequiredVFO to select (VFOA, VFOB, VFOC, currVFO, VFO, MEM, Main, Sub).
cURL
1curl -X POST "http://localhost:4532/api/radio/vfo" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "vfo": "VFOA"
6  }'
GET
/api/rotator/position

Get the current antenna rotator position. Returns azimuth (0-360 degrees) and elevation (0-90 degrees) of the antenna.

cURL
1curl -X GET "http://localhost:4532/api/rotator/position" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json"
POST
/api/rotator/position

Set the antenna rotator position. Specify target azimuth and elevation for the antenna to move to. The rotator will begin moving immediately.

Parameters

NameTypeRequiredDescription
azimuthnumberRequiredTarget azimuth in degrees (0.0 - 360.0).
elevationnumberOptionalTarget elevation in degrees (0.0 - 90.0). Defaults to 0.
cURL
1curl -X POST "http://localhost:4532/api/rotator/position" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "azimuth": 180.5,
6    "elevation": 45.0
7  }'

API Playground

Test API endpoints interactively. Select an endpoint, configure parameters, and try it out.

vfo
Generated cURL Command
1curl -X GET "http://localhost:4532/api/radio/frequency?vfo=currVFO" \
2  -H "X-API-Key: your-api-key" \
3  -H "Content-Type: application/json"