- Home
- Developers
- API Documentation
Technical specification · v2
Morse Code API Documentation
Reference for the CodigoMorse.io signalling interface: a RESTful implementation of the Morse protocol for low-latency text transmission. Authentication, endpoints, parameters, responses and rate limits, with request samples in curl, JavaScript and Python.
Base URL
https://api.codigomorse.io/v2
All endpoints below are relative to this base. HTTPS only.
Authentication
Bearer token in the Authorization header.
Keys are generated in the Engineering Console under the KEYS module.
Rate limits
Standard: 10 req/s (1,000 requests per hour)
Enterprise: unlimited. Limits apply per key.
Good to know. Every tool on this website (translator, decoder, audio player) runs entirely in your browser and does not depend on this API. If you only need to convert text to Morse inside your own code, the developer guide shows how to do it offline in a few lines of JavaScript, Python or PHP, with no key required.
01 · Authentication
All requests must include a Bearer token in the Authorization header. Tokens are generated in the Engineering Console under the KEYS module. Requests without a valid token receive 401 Unauthorized; requests with a token that lacks permission for an endpoint receive 403 Forbidden.
| Method | Bearer Token |
|---|---|
| Header | Authorization: Bearer <key> |
| Transport | HTTPS (TLS 1.2 or newer) |
Keep the key on your server or in an environment variable. Never ship it inside a public web page or a mobile app bundle; anyone who can read the page can read the key.
Reference
02 · Morse Code API endpoints
Three endpoints cover the full cycle: encode and transmit a message, poll for decoded signals, or subscribe to the live stream over WebSocket.
Encodes a text string into a binary Morse sequence and transmits it to the specified node cluster. The call returns immediately with 202 Accepted and a job identifier; the transmission continues asynchronously.
Request parameters
| Name | Type | Description |
|---|---|---|
| message | string | Alphanumeric string to encode. Maximum 1,024 characters. Letters, digits and the punctuation marks of the International Morse table are accepted; other characters are dropped. |
| priority | integer | Standard (0) or Urgent (1). Urgent jobs are scheduled ahead of standard ones. |
| wpm | integer | Words per minute for the generated timing. Default: 20. Dot length = 1.2 / wpm seconds (PARIS standard). |
JSON body · application/json
{
"message": "SOS",
"priority": 1,
"wpm": 25
}Response · 202 Accepted
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"status": "broadcasting",
"sequence": "... --- ...",
"job_id": "tx_9921_alpha"
}curl -X POST https://api.codigomorse.io/v2/transmit \
-H 'Authorization: Bearer MORSE_KEY_***' \
-H 'Content-Type: application/json' \
-d '{"message": "SOS", "priority": 1, "wpm": 25}'const res = await fetch('https://api.codigomorse.io/v2/transmit', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + process.env.MORSE_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({ message: 'SOS', priority: 1, wpm: 25 })
});
const job = await res.json(); // { status, sequence, job_id }
console.log(job.sequence); // "... --- ..."import os, requests
res = requests.post(
'https://api.codigomorse.io/v2/transmit',
headers={'Authorization': f"Bearer {os.environ['MORSE_API_KEY']}"},
json={'message': 'SOS', 'priority': 1, 'wpm': 25},
timeout=10,
)
res.raise_for_status()
job = res.json() # {'status': 'broadcasting', 'sequence': '... --- ...', 'job_id': 'tx_9921_alpha'}
print(job['sequence'])Queries the active receiver for incoming transmissions. Returns an array of decoded signals processed in the last 5 minutes. The endpoint takes no parameters; the window is fixed and results are ordered newest first.
Each item in the array is one decoded signal, carrying its UTC capture time and the decoded content. Poll it when a WebSocket connection is not practical (serverless functions, cron jobs); for continuous consumption use /stream instead.
Data stream preview
curl https://api.codigomorse.io/v2/receive \
-H 'Authorization: Bearer MORSE_KEY_***'const res = await fetch('https://api.codigomorse.io/v2/receive', {
headers: { 'Authorization': 'Bearer ' + process.env.MORSE_API_KEY }
});
const signals = await res.json(); // array of decoded signals (last 5 minutes)
signals.forEach(s => console.log(s));import os, requests
res = requests.get(
'https://api.codigomorse.io/v2/receive',
headers={'Authorization': f"Bearer {os.environ['MORSE_API_KEY']}"},
timeout=10,
)
for signal in res.json(): # decoded signals from the last 5 minutes
print(signal)WebSocket endpoint: the live Morse stream. Open a socket to receive frames as they are decoded instead of polling /receive. Authenticate with the same key, passed as the token query parameter because browsers cannot set custom headers on a WebSocket handshake.
const ws = new WebSocket('wss://api.codigomorse.io/v2/stream?token=' + MORSE_API_KEY);
ws.onmessage = (event) => {
const frame = JSON.parse(event.data);
console.log(frame); // live Morse stream frames
};Health check used in the authentication example above. Returns 200 OK when the API and your key are both valid. Use it to verify a new key before wiring up the other endpoints, or as an uptime probe. The human-readable equivalent is the system status page.
03 · Rate limiting
Requests are limited according to your subscription tier. Standard access is limited to 1,000 requests per hour, with bursts of up to 10 requests per second. Enterprise keys have no limit. When a limit is exceeded the API answers 429 Too Many Requests; back off and retry after the interval indicated in the Retry-After header.
Errors
Errors use standard HTTP status codes with a JSON body of the form {"error": "message"}:
| Status | Meaning |
|---|---|
| 400 | Malformed JSON, missing message, or message longer than 1,024 characters. |
| 401 | Missing or invalid Bearer token. |
| 403 | The key is valid but not allowed to use this endpoint. |
| 429 | Rate limit exceeded. Honor Retry-After. |
| 5xx | Transient server problem. Retry with exponential backoff. |
Encoding notes
The sequence field uses the same notation as the website: . for a dot, - for a dash, one space between letters and / between words. Characters are encoded according to ITU-R M.1677-1, the same table our Morse code chart prints. Accented letters are mapped to their base letter; characters with no Morse equivalent are ignored.
FAQ
Frequently asked questions
Do I need the API to translate text to Morse code?
No. The translator on this site runs in your browser, and the developer guide shows how to encode and decode Morse in your own code without any network call. The API is for applications that need the hosted transmit/receive pipeline.
How do I get an API key?
Keys are issued through the Engineering Console under the KEYS module. If you do not have console access, contact us describing your use case and expected volume.
What does the "sequence" field contain?
The encoded message in standard notation: dots, dashes, a space between letters and a slash between words. For SOS it is ... --- ....
What is the default speed?
20 words per minute, which gives a 60 ms dot. Pass wpm to change it; 5 to 15 WPM is typical for learners, 20 to 30 for experienced operators.
Is there a sandbox?
Use GET /status to verify a key without creating a transmission. For local development you can also encode with the offline snippets in the developer guide and compare the output with the API.
Build with Morse code
Read the developer guide for offline encoding, timing math and audio generation.